PHANTASM

T85 · v1.0.0 · AI Fleet Detection & Topology Mapping Engine

PHANTASM is the reconnaissance layer of the NIGHTFALL offensive framework. It answers "does this target have an AI fleet, how large is it, and what does the stack look like?" before any offensive tool is deployed.

What is PHANTASM

PHANTASM layers 8 subsystems — passive OSINT, certificate transparency, DNS enumeration, TCP port sweeping, HTTP protocol fingerprinting, behavioural timing analysis, honeypot detection, and weighted fleet scoring — to produce a structured intelligence report about a target's AI surface.

Reports are signed with Ed25519 and include a SHA-256 hash-chained evidence log. The CENSUS subsystem classifies the fleet into one of six tiers (NONE → ENTERPRISE) and recommends specific NIGHTFALL tools for the next engagement phase.

Installation

# Clone the repository
git clone https://github.com/RichardBarron27/red-specter-phantasm
cd red-specter-phantasm

# Install in editable mode (Python 3.11+)
pip install -e .

# Verify installation
specter-phantasm --help

# Generate signing keypair (stores in keys/)
specter-phantasm keygen

Dependencies

Quickstart

# Passive scan — no target contact, no gate required
specter-phantasm passive target.org --format text

# Full survey with UNLEASHED scope file
specter-phantasm survey target.org --scope scope.json -o report.json

# scope.json minimum structure
{
  "unleashed_active": true,
  "target": "target.org",
  "operator": "red-team-op-001"
}

8 Subsystems

SS-01: SPECTER-EYE

Passive OSINT aggregation. Queries the GitHub search API for AI-topic repositories associated with the target organisation, performs passive crt.sh lookups, queries Shodan and Censys for host banners if API keys are provided.

SS-02: CERBERUS-CERT

Mines certificate transparency logs via crt.sh JSON API. Extracts CNs and SANs matching 29 AI-pattern subdomains, then resolves discovered FQDNs via dnspython and socket fallback. Also enumerates AI-pattern subdomains directly.

AI subdomain patterns: ai llm agent agents inference infer embeddings embed rag mcp a2a chat copilot assistant orchestrator gateway proxy model models ml nlp gpt claude gemini api-ai vector kb knowledgebase pipeline genai

SS-03: BEACON-SCAN

Async TCP connect scan using asyncio.open_connection() with a semaphore of 20 concurrent connections. Default jitter of 0.1s (disabled in aggressive mode). Scans 22 known AI service ports.

SS-04: MIRAGE

HTTP protocol fingerprinting. Probes 12 well-known AI paths on each open port. Classifies response body against regex patterns for Ollama, OpenAI-compat, A2A, MCP, Triton, Gradio, Streamlit, and Prometheus AI metrics.

SS-05: TIMESTAMP

Collects 5 latency samples per endpoint via httpx.stream() (TTFB). Detects SSE and chunked transfer-encoding responses. Classifies inference patterns and estimates model size class.

SS-06: WRAITH-CHECK

Honeypot detection signals checked per endpoint:

SS-07: LATTICE

Builds a networkx.DiGraph() from all subsystem outputs. Node IDs are 12-char MD5(host:port) hashes. Inferred edge relationships:

SS-08: CENSUS

Weighted scoring aggregation. Score per signal type:

Fleet Tiers

UNLEASHED Gate

PHANTASM uses a three-level gate matching the broader NIGHTFALL UNLEASHED framework.

Scope File

{
  "unleashed_active": true,
  "clearance_level": "DESTROY",
  "target": "target.org",
  "operator": "op-2026-001",
  "targets": ["target.org", "10.0.0.0/24"]
}

The scope file is located at $PHANTASM_SCOPE (env var) or phantasm_scope.json in the current directory.

CLI: survey

specter-phantasm survey [OPTIONS] TARGET

Options:
  --passive-only          No port scanning or HTTP probing
  --no-cert               Skip certificate transparency
  --aggressive            TCP scan without jitter (DESTROY clearance)
  --stop-on-honeypot      Abort on first honeypot detection
  --format [json|jsonld|graphml|mermaid|text]
                          Output format (default: json)
  --output / -o PATH      Write to file (default: stdout)
  --scope PATH            Scope file (overrides PHANTASM_SCOPE)
  --samples INT           Timing samples per endpoint (default: 5)
  --timeout FLOAT         Per-request timeout in seconds (default: 5.0)

CLI: passive

specter-phantasm passive [OPTIONS] TARGET

Shortcut for survey --passive-only. Only queries DNS, CT logs, and OSINT.
Does not contact the target directly.

Options:
  --format [json|jsonld|graphml|mermaid|text]
  --output / -o PATH
  --no-cert

CLI: report

specter-phantasm report [OPTIONS] REPORT_FILE

Re-render an existing PHANTASM report in a different format.
REPORT_FILE must be a valid PHANTASM JSON report.

Options:
  --format [json|jsonld|graphml|mermaid|text]
  --output / -o PATH

CLI: keygen

specter-phantasm keygen

Generate a new Ed25519 keypair for report signing.
Stored in keys/phantasm_private.pem and keys/phantasm_public.pem.

Output: JSON

Default format. Full Pydantic model serialisation including all subsystem outputs, evidence chain, and Ed25519 signature.

{
  "report_id": "FLT-AB12CD34EF56",
  "target": "example.com",
  "generated_at": "2026-05-14T17:30:00+00:00",
  "fleet_tier": "MEDIUM",
  "fleet_tier_description": "Medium fleet (6–20 nodes)",
  "confidence_score": 0.45,
  "census_score": { "total_score": 27.0, "tier": "MEDIUM", ... },
  "endpoints": [...],
  "topology": { "nodes": [...], "edges": [...] },
  "evidence_chain": [...],
  "ed25519_signature": "a3b4c5..."
}

Output: JSON-LD

Schema.org + https://red-specter.co.uk/nightfall/phantasm/vocab# vocabulary. Nodes use urn:phantasm:node:{node_id} URIs.

Output: GraphML

Generated via networkx.generate_graphml(). Importable into Gephi, yEd, Neo4j, and any GraphML-compatible tool. Returns null if no topology nodes were discovered.

Output: Mermaid

Flowchart TD layout. Honeypot nodes styled with fill:#ff6666. Auto-suppressed (returns null) when topology exceeds 50 nodes to prevent unreadable output.

Report ID & Signing

Report IDs have the format FLT-{12 hex chars} generated from secrets.token_hex(6).upper(). Reports are signed with Ed25519 over the JSON-serialised report body (all fields except ed25519_signature itself), keys sorted, no whitespace. Verification: verify_report(report_dict) → bool.

The SHA-256 evidence chain hashes each event as: SHA256(prev_hash:event:data), forming a tamper-evident log.

NIGHTFALL Tool Handoff

The handoff_targets array in the JSON report provides structured targets for downstream NIGHTFALL tools:

{
  "host": "10.0.0.1",
  "port": 11434,
  "service": "ollama",
  "models": ["llama3:8b", "mistral:7b"],
  "source": "mirage",
  "score": 5.0
}

The recommended_tools array lists NIGHTFALL tools ordered by priority for the detected fleet composition. Recommendations are deterministic — same fleet composition always produces the same ordered tool list.

Environment Variables