Plugin & Extension SDK
Extend PhantomYerra with custom scanners, report templates, and payload sets. The SDK provides a clean, well-documented interface for building extensions that integrate seamlessly with the platform's AI engine, evidence pipeline, and reporting system.
Overview
The PhantomYerra SDK lets you build three types of extensions:
| Extension Type | What It Does | Guide |
|---|---|---|
| Custom Scanner | Add new vulnerability detection capabilities. Your scanner runs alongside PhantomYerra's built-in engines, receives targets from the orchestrator, and produces findings with evidence. | Custom Scanner Guide |
| Custom Report Template | Design custom report layouts, branding, and compliance sections. Use Jinja2 templates with full access to scan data, findings, evidence, and metadata. | Custom Report Template Guide |
| Custom Payloads | Add new payload sets for specific vulnerability classes, technologies, or targets. Custom payloads are available in the Intruder and to automated scanners. | Custom Payloads Guide |
SDK Architecture
Extensions integrate with PhantomYerra through a plugin interface. Every extension is a self-contained Python module that follows a standard contract:
- Discovery — PhantomYerra scans the
extensions/directory on startup and loads any valid plugin module. - Registration — Each plugin registers itself with the surface registry, declaring what attack surfaces it handles and what capabilities it provides.
- Execution — The AI orchestrator invokes plugins during automated scans based on target profile and attack surface mapping. Plugins can also be invoked manually.
- Output — All plugins produce standardized Finding objects with severity, evidence, PoC steps, and remediation. These flow into the same reporting pipeline as built-in findings.
Extension Directory Structure
Getting Started
-
1
Create the Extension Directory
Create a new folder inside
extensions/with a descriptive name (e.g.,my-custom-scanner). Add an__init__.pyfile. -
2
Implement the Interface
Subclass
BaseToolAdapterfor scanners, create a Jinja2 template for reports, or write a payload file for custom payloads. See the individual guides for details. -
3
Register with PhantomYerra
Call the appropriate registration function in your
__init__.py. PhantomYerra discovers and loads your extension on next startup. -
4
Test
Run your extension against a test target. Verify findings appear in the UI, evidence is captured, and reports include your data.
Core SDK Classes
| Class / Function | Purpose | Module |
|---|---|---|
BaseToolAdapter | Base class for all custom scanners. Subclass this and implement scan(). | phantomyerra.sdk.base |
Finding | Standardized vulnerability finding object with severity, evidence, PoC, remediation. | phantomyerra.sdk.finding |
Evidence | Evidence attachment (request/response, screenshot, file). Automatically SHA-256 hashed. | phantomyerra.sdk.evidence |
surface_registry.register() | Register your scanner for specific attack surfaces. | phantomyerra.sdk.registry |
emit_activity() | Send real-time status updates to the UI during scanning. | phantomyerra.sdk.events |
PayloadSet | Container for custom payload lists with metadata and processing rules. | phantomyerra.sdk.payloads |
Best Practices
- Always validate scope — Before sending any request, verify the target is within the engagement scope using
scope_checker.is_in_scope(url). - Emit activity events — Call
emit_activity()during each phase of your scan so users see real-time progress in the UI. - Capture evidence — Every finding must include raw evidence (HTTP request/response, command output, or screenshot). Never create findings without proof.
- Handle errors gracefully — Wrap all network calls in try/except. Return partial results rather than crashing the entire scan.
- Respect rate limits — Honor the global rate-limit settings. Use
await rate_limiter.acquire()before each request. - Thread safety — Extensions may run concurrently. Use thread-safe data structures and avoid shared mutable state.
- No hardcoded secrets — Never embed API keys, credentials, or tokens in your extension code.