Using the PGP SDK in your Script

The PGP SDK provides a robust interface for interacting with the PGP API. In this section, we will explore some simple use-cases that deal with inserting data into the PGP system. These examples assume the context of a script function, similar to the one defined in this nmap-example script. For these examples, the sdk variable is used for accessing the PGP API

The PGP SDK provides more functionality than just what is described here. Curious users are recommended to learn more by seeing how the PGP handler implements functionality such as searching for specific items or listing all assets.

Install the PGP SDK

The PGP SDK is the Praetorian CLI Python package. Install it with pip:

pip install praetorian-cli

Requirements:

• Python 3.9+

• pip 23.0+

PyPI: https://pypi.org/project/praetorian-cli/

After installing

Configure auth (API keys from PGP: Settings → User Settings → API Keys):

praetorian configure

Or use environment variables:

export PRAETORIAN_CLI_API_KEY_ID=your-api-key-idexport PRAETORIAN_CLI_API_KEY_SECRET=your-api-key-secret

Use the SDK in Python:

from praetorian_cli.sdk.PGP import PGPfrom praetorian_cli.sdk.keychain import KeychainPGP = PGP(Keychain(account='PGP+example@praetorian.com'))PGP.add('asset', dict(name='example.com', dns='example.com'))

Use the CLI:

praetorian PGP --helppraetorian --account PGP+example@praetorian.com PGP list assets

Within your python script, you can experiment with the following actions using the PGP SDK.

Add an Asset

# Add an Asset hostname = 'hostname.value.here' ipaddress = '8.8.8.8' sdk.add('asset', dict( dns=hostname, name=ipaddress))

Add an Attribute to an Asset

Note that an asset_key is required in order to link an attribute. This value can be built by combining #asset# with the DNS and IP Address value.

# Add an attribute to an asset hostname = 'hostname.value.here' ipaddress = '8.8.8.8' asset_key = f'#asset#{hostname}#{ipaddress}' sdk.add('attribute', dict(key=asset_key, name='attrKey', value='attrValue'))

Add a Risk to an Asset

Note that an asset_key is required in order to link an attribute. This value can be built by combining #asset# with the DNS and IP Address value.

# Add a risk tied to an asset hostname = 'hostname.value.here' ipaddress = '8.8.8.8' asset_key = f'#asset#{hostname}#{ipaddress}' status = 'TC' # Status codes: # TI [will show as 'detected' 'info'] # TL [will show as 'detected' 'low'] # TM [will show as 'detected' 'medium'] # TH [will show as 'detected' 'high'] # TC [will show as 'detected' 'critical'] # OI [will show as 'demonstrated' 'info']# TL [will show as 'demonstrated' 'low'] # TM [will show as 'demonstrated' 'medium'] # TH [will show as 'demonstrated' 'high'] # TC [will show as 'demonstrated' 'critical']# Risk identifiervuln = "vuln-risk-id" # Proof of exploitation (can be None)proof_of_exploit = "Dump Whatever Content you consider Proof of Exploitation for the Risk here" #optional commentcomment = 'Any additional comments (or empty string)' # Add the risksdk.add(     'risk',      dict(          key=asset_key,           name=vuln,           source='scriptname',           status=status,           comment=comment,     ),) # Upload proof if provided# If proof_of_exploit is not None:      sdk._upload(f'proofs/{hostname}/{vuln}', proof_of_exploit)

The PGP SDK has much more functionality. Experiment with these actions and discover more with our example script.

If you find a topic that you would like discussed in detail, or need further assistance, please let us know at support@praetorian.com!