PGP API Technical User Guide

PGP API Technical User Guide

This guide provides comprehensive documentation for working with the PGP API programmatically. It covers authentication, API endpoints, request/response formats, and practical examples.

Overview

The PGP API provides programmatic access to Praetorian's offensive security platform. You can use it to:

• Query and manage assets in your attack surface
• Retrieve security risks and vulnerabilities
• Create and manage seeds for discovery
• Monitor scan jobs and their status
• Configure integrations and webhooks

Base URL

https://d0qcl2e18h.execute-api.us-east-2.amazonaws.com/PGP/api/v1

Authentication

Getting Your API Keys

1. Log in to the PGP Platform
2. Navigate to Settings → User Settings → API Keys
3. Click Create API Key
4. Provide a name and expiration date (max 1 year)
5. Important: Copy your API key secret immediately—it is only displayed once!

Note for SSO Organizations: Users in SSO-enabled organizations should also use API Keys for programmatic access.

API Key Format

When you create an API key, you receive:

Obtaining an Access Token

Exchange your API key for a JWT access token:

curl -X GET "https://d0qcl2e18h.execute-api.us-east-2.amazonaws.com/PGP/token?id=YOUR_API_KEY_ID&key=YOUR_API_KEY_SECRET"

Response:

{  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6...",  "IdToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6..."}

Token Lifetime: Access tokens are valid for 1 hour (3600 seconds). Cache and reuse tokens to avoid unnecessary requests.

Making Authenticated Requests

Include the token in the Authorization header:

curl -X GET "https://d0qcl2e18h.execute-api.us-east-2.amazonaws.com/PGP/api/v1/assets"   -H "Authorization: Bearer YOUR_TOKEN"   -H "Content-Type: application/json"

API Endpoints

Assets

Retrieve discovered assets in your attack surface.

List Assets

curl -X GET "https://d0qcl2e18h.execute-api.us-east-2.amazonaws.com/PGP/api/v1/assets"   -H "Authorization: Bearer YOUR_TOKEN"

Response:

{  "assets": [    {      "key": "#asset#example.com#192.168.1.1",      "dns": "example.com",      "name": "192.168.1.1",      "source": "discovered",      "status": "A",      "created": "2024-01-15T10:30:00Z",      "updated": "2024-01-15T10:30:00Z"    }  ],  "offset": "next_page_token"}

Risks

Retrieve security risks and vulnerabilities.

List Risks

curl -X GET "https://d0qcl2e18h.execute-api.us-east-2.amazonaws.com/PGP/api/v1/risks"   -H "Authorization: Bearer YOUR_TOKEN"

Response:

{  "risks": [    {      "key": "#risk#example.com#CVE-2024-1234",      "dns": "example.com",      "name": "CVE-2024-1234",      "status": "O",      "severity": "CRITICAL",      "cvss_score": 9.8,      "created": "2024-01-15T10:30:00Z"    }  ],  "offset": "next_page_token"}

Seeds

Manage discovery seeds (starting points for asset enumeration).

Create Seed

curl -X POST "https://d0qcl2e18h.execute-api.us-east-2.amazonaws.com/PGP/api/v1/seeds"   -H "Authorization: Bearer YOUR_TOKEN"   -H "Content-Type: application/json"   -d '{"dns": "example.com"}'

List Seeds

curl -X GET "https://d0qcl2e18h.execute-api.us-east-2.amazonaws.com/PGP/api/v1/seeds"   -H "Authorization: Bearer YOUR_TOKEN"

Jobs

Monitor scan jobs and their status.

curl -X GET "https://d0qcl2e18h.execute-api.us-east-2.amazonaws.com/PGP/api/v1/jobs"   -H "Authorization: Bearer YOUR_TOKEN"

API Keys

Create API Key

curl -X POST "https://d0qcl2e18h.execute-api.us-east-2.amazonaws.com/PGP/api/v1/key"   -H "Authorization: Bearer YOUR_TOKEN"   -H "Content-Type: application/json"   -d '{"name": "my-api-key", "expires": "2025-12-31T23:59:59Z"}'

Response:

{  "key": "#key#12345678-1234-1234-1234-123456789abc",  "name": "my-api-key",  "secret": "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567",  "expires": "2025-12-31T23:59:59Z",  "creator": "user@example.com",  "status": "A",  "created": "2024-01-15T10:30:00Z"}

Important: The secret field is only returned once during creation. Store it securely.

Webhooks

Create Webhook

curl -X POST "https://d0qcl2e18h.execute-api.us-east-2.amazonaws.com/PGP/api/v1/webhook"   -H "Authorization: Bearer YOUR_TOKEN"   -H "Content-Type: application/json"   -d '{"url": "https://your-endpoint.com/webhook"}'

Response Codes

Rate Limiting

• Limit: 5,000 requests per IP address (sliding window)
• Response: HTTP 429 when exceeded
• Recommendation: Implement exponential backoff for retries

Pagination

List endpoints support pagination via the offset parameter:

# First pagecurl -X GET "https://d0qcl2e18h.execute-api.us-east-2.amazonaws.com/PGP/api/v1/assets"   -H "Authorization: Bearer YOUR_TOKEN"# Subsequent pages (use offset from previous response)curl -X GET "https://d0qcl2e18h.execute-api.us-east-2.amazonaws.com/PGP/api/v1/assets?offset=OFFSET_VALUE"   -H "Authorization: Bearer YOUR_TOKEN"

When offset is present in the response, more results are available. When absent, you've reached the last page.

Python SDK

For Python applications, use the official Praetorian CLI/SDK:

pip install praetorian-cli

Example Usage:

from praetorian_cli.sdk.PGP import PGPfrom praetorian_cli.sdk.keychain import Keychain# Initialize with your accountPGP = PGP(Keychain(account='your-account@example.com'))# List assetsassets = PGP.list('asset')# Add a seedPGP.add('seed', dict(dns='example.com'))# Get risksrisks = PGP.list('risk')

Environment Variables:

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

Best Practices

1. Cache tokens: Reuse access tokens for their full 1-hour lifetime
2. Handle pagination: Always check for offset in responses
3. Implement retries: Use exponential backoff for 429 and 502 errors
4. Secure credentials: Never commit API keys to version control
5. Monitor rate limits: Stay well below 5,000 requests per window

Support

• Documentation: docs.praetorian.com
• GitHub Issues: praetorian-inc/PGP-ui
• Email: support@praetorian.com