REST API Reference

Pulsar provides a RESTful API built on the Django REST Framework (DRF), allowing users to programmatically manage assets, trigger scans, and retrieve discovery data. All endpoints follow standard REST conventions and return data in JSON format.

Authentication

Pulsar supports several authentication methods to accommodate both web-based interaction and automated scripts.

Token Authentication

Recommended for automation and external integrations. Include the token in the Authorization header.

Authorization: Token your_api_token_here

Basic Authentication

Uses standard Base64-encoded credentials.

Authorization: Basic <base64_encoded_username:password>

Session Authentication

Used primarily by the frontend Vue.js application. For state-changing requests (POST, PUT, DELETE), a CSRF token must be provided in the X-CSRFToken header.

Global Features

Filtering and Search

Most list endpoints support filtering via query parameters using the DjangoFilterBackend. You can filter results based on ownership and specific resource attributes.

Example: GET /api/assets/?name=InternalNetwork

Pagination

List responses are paginated to ensure performance. The default page size is 10 items.

• count: Total number of items.
• next: URL for the next page.
• previous: URL for the previous page.
• results: Array of objects.

Endpoint Reference

Assets

Assets are the top-level containers for organization infrastructure. Access is restricted to the owner and members of assigned collaboration groups.

| Method | Endpoint | Description | | :--- | :--- | :--- | | GET | /api/assets/ | List all accessible assets. | | POST | /api/assets/ | Create a new asset container. | | GET | /api/assets/{id}/ | Retrieve details of a specific asset. | | PUT | /api/assets/{id}/ | Update asset metadata. | | DELETE | /api/assets/{id}/ | Remove an asset and its associated discovery data. |

Asset Schema

{
    "id": 1,
    "name": "Target Org",
    "description": "Public facing web assets",
    "owner": "admin",
    "collaborations": ["RedTeam_Alpha"],
    "created_at": "2023-10-27T10:00:00Z"
}

Domains

Discovery results representing subdomains and TLDs found during scans.

| Method | Endpoint | Description | | :--- | :--- | :--- | | GET | /api/domains/ | List discovered domains. | | GET | /api/domains/?asset={id} | Filter domains by asset ID. | | GET | /api/domains/{id}/ | Retrieve specific domain findings, including scan history. |

IPv4 Addresses

Network-level data associated with discovered domains.

| Method | Endpoint | Description | | :--- | :--- | :--- | | GET | /api/ips/ | List all discovered IP addresses. | | GET | /api/ips/?domain={id} | Filter IPs by domain ID. |

Scan Operations

Scans are managed via actions on the API resources.

Triggering a Scan

To start a discovery or vulnerability scan, use the run_scan or dispatch_scan actions.

Endpoint: POST /api/assets/{id}/run_scan/

Request Body:

{
    "policy": "aggressive_discovery",
    "target": "example.com"
}

Response Status Codes

| Code | Meaning | Description | | :--- | :--- | :--- | | 200 OK | Success | The request was successful. | | 201 Created | Created | Resource (Asset/Policy) created successfully. | | 400 Bad Request | Validation Error | Parameters are missing or malformed. | | 401 Unauthorized | Auth Error | Invalid or missing credentials. | | 403 Forbidden | Permission Denied | You do not own this asset or belong to the collaboration group. | | 404 Not Found | Not Found | The requested resource ID does not exist. |

Integration with External Tools

The Pulsar API is designed to be consumed by custom scanner extensions or CI/CD pipelines.

Example: Python Request

import requests

API_URL = "http://pulsar-instance/api/assets/"
TOKEN = "your_api_token"

headers = {
    "Authorization": f"Token {TOKEN}",
    "Content-Type": "application/json"
}

# Fetch all assets
response = requests.get(API_URL, headers=headers)
assets = response.json()

for asset in assets['results']:
    print(f"Asset: {asset['name']} (ID: {asset['id']})")