Custom Scanner Extensions

Pulsar is designed to be modular, allowing users to extend its discovery and scanning capabilities beyond the integrated toolset (like Nmap or Amass). This is achieved through the Sandbox module, which provides a controlled environment for executing internal scripts or third-party tools.

The Sandbox Module

The Sandbox acts as the interface between Pulsar's task scheduler (Celery) and your custom logic. By adding extensions, you can integrate proprietary vulnerability checks, specialized OSINT scripts, or wrappers for other CLI tools.

Creating a Custom Extension

To add a new extension, you must create a Python script within the portal/pulsar/modules/ directory. Extensions are expected to follow a specific execution pattern to ensure Pulsar can parse the findings and associate them with the correct assets.

Script Requirements

1. Input: Your script should accept targets (IPs, Domains, or CIDR blocks) via command-line arguments.
2. Output: To integrate results into the Pulsar dashboard, the script should return data in a structured format (JSON preferred) or write findings to the Pulsar database using the internal API.

Example of a basic skeleton for an extension:

# portal/pulsar/modules/custom_checker.py

def run_extension(target, settings):
    """
    Entry point for Pulsar Sandbox.
    :param target: String (Domain or IP)
    :param settings: Dictionary of scan parameters from the Policy
    """
    # Custom logic here (e.g., calling a subprocess or an API)
    results = {
        "target": target,
        "vulnerabilities": [],
        "metadata": {}
    }
    
    # Logic to identify a weakness
    # ...
    
    return results

Integrating Extensions into Scan Policies

Once your script is placed in the modules directory, it must be registered within Pulsar to be available for automated scans.

1. Define the Extension: Navigate to the Scan Settings in the Web UI.
2. Add Entry: Create a new Scanner entry pointing to your script.
3. Configure Parameters: Define which arguments Pulsar should pass to your script (e.g., timeout, intensity, or custom API keys).

Policy Assignment

After registration, your custom scanner will appear in the Scan Policies menu. You can toggle it on or off for specific scan profiles, allowing you to run "Lightweight" scans with just standard tools or "Deep" scans that include your custom extensions.

Data Schema for Results

To ensure that findings from your extension are correctly visualized in the Pulsar graph and vulnerability list, return an object matching the following structure:

| Field | Type | Description | | :--- | :--- | :--- | | name | String | The name of the vulnerability or finding. | | severity | Integer | 1 (Info) to 4 (Critical). Used for the risk score. | | description | String | Detailed information about the finding. | | remediation | String | Steps to fix the identified issue. | | raw_output | String | The full output from the underlying tool for debugging. |

Sandbox Security Considerations

The Sandbox module executes scripts with the same privileges as the Pulsar Celery worker. When writing extensions:

• Sanitize Inputs: Ensure that target strings are validated before being passed to shell commands to prevent command injection.
• Resource Limits: Pulsar tracks task execution time. If your custom extension hangs, the Sandbox will terminate the process based on the SCAN_TIMEOUT defined in your global settings.
• Dependencies: If your script requires external Python libraries, install them within the Pulsar virtual environment.