The scan lifecycle

A full Ghost Security Agent scan follows a structured pipeline: build context, run parallel scans, aggregate findings, optionally validate, fix, and/or generate a report.

The pipeline

Each stage produces artifacts that flow into the next. Everything is cached locally at ~/.ghost/repos/<repo_id>/ so subsequent runs are incremental.

Stage 1: Repository context

Skill: ghost:repo-context

Before scanning anything, Ghost Security Agent builds a shared understanding of your codebase. This context informs every scan that follows.

The context-building process works in two passes:

1. Detection -- discovers all distinct technology stacks in the repository (backend, frontend, mobile, CLI, library, infrastructure-as-code). Maps the directory structure and identifies dependency files.
2. Summarization -- for each detected project, samples key directories and files to assess business criticality, identify sensitive data types (PII, payment, authentication, health, financial), and write an architectural summary.

The output is a repo.md file cached at ~/.ghost/repos/<repo_id>/cache/repo.md. This file is read by every subsequent skill to make informed decisions about what to scan and how to prioritize findings.

Stage 2: Parallel scans

Three scans run in parallel, each focused on a different class of vulnerability:

Dependency scanning (ghost:scan-deps)

1. Discover -- finds all lockfiles in the repository (go.mod, package-lock.json, Gemfile.lock, Cargo.lock, etc.)
2. Scan -- runs Wraith against each lockfile, querying the OSV database for known CVEs
3. Analyze -- for each vulnerability found, AI analyzes exploitability: Is the vulnerable function actually called? Can user input reach it? Is this production code or a test dependency?
4. Summarize -- generates a report with coverage statistics and confirmed findings

Secret scanning (ghost:scan-secrets)

1. Scan -- runs Poltergeist against the codebase using 100 built-in rules
2. Analyze -- for each match, AI assesses context: Is this a real secret or a placeholder? Is it hardcoded or loaded from an environment variable? Is it in production code or test fixtures?
3. Summarize -- generates a report separating confirmed risks from false positives

Code analysis (ghost:scan-code)

1. Plan -- reads the repository context and selects vulnerability vectors to check based on the project type and depth setting (quick: top 5, balanced: top 15, full: all vectors)
2. Nominate -- fast-triages files using pattern matching to identify candidates for each vulnerability vector
3. Analyze -- deep analysis of nominated files: traces data flows from user input to dangerous sinks, checks for mitigations, validates against structured criteria
4. Verify -- independent verification of each finding by a separate analysis pass that checks for missed mitigations and confirms all criteria are met

Each scan writes its findings as individual Markdown files to ~/.ghost/repos/<repo_id>/scans/<commit_sha>/<scan_type>/findings/.

Stage 3: Validation

Skill: ghost:validate

For findings that need proof, the validate skill performs deeper investigation:

1. Code analysis -- reads the vulnerable file, traces the request flow from route registration through middleware to handler, and verifies the specific claim (e.g., "authorization check is missing")
2. Live testing (when available) -- starts a Reaper proxy scoped to the application's domain, captures traffic to the vulnerable endpoint, and attempts to demonstrate the exploit

The result is a determination: true positive, true positive (confirmed with live test), false positive, or inconclusive, along with detailed evidence.

Validation is per-finding and interactive. You choose which findings to validate based on the report.

Stage 4: Report

Skill: ghost:report

The report skill aggregates findings from all completed scans into a single prioritized document.

It reads every finding file, filters by confidence (excluding rejected and false-positive findings), and sorts by severity. The output is a report.md that inlines the full content of each finding: the actual vulnerability details, code snippets, and remediation guidance.

The report includes:

• Executive summary -- overall security posture with business context
• Critical and high findings -- full details inlined for each finding
• Medium findings -- full subsections, not condensed
• Scan coverage -- statistics per scan type (candidates found, confirmed, false positives)
• Methodology -- notes on what each scan covered and how

Low-severity findings are omitted from the combined report but remain available in the per-scan output directories.

Caching and incremental runs

Ghost Security Agent caches at two levels:

• Repository context (~/.ghost/repos/<repo_id>/cache/) -- shared across all scans, regenerated when you ask for it
• Scan results (~/.ghost/repos/<repo_id>/scans/<commit_sha>/) -- per-commit, so re-scanning the same commit returns cached results

Your first scan builds context and runs all analyzers. Subsequent scans on the same commit are instant. When you push new code, only the changed commit triggers a fresh scan.

Running individual stages

You don't have to run the full pipeline. Each skill works independently:

# Just scan secrets
claude "/ghost:scan-secrets"

# Just scan dependencies
claude "/ghost:scan-deps"

# Just run code analysis at full depth
claude "/ghost:scan-code depth=full"

# Generate a report from existing scan results
claude "/ghost:report"

# Validate a specific finding
claude "/ghost:validate path/to/finding.md"

The only prerequisite is that ghost:repo-context should run before ghost:scan-code, since code analysis uses the repository context to plan which vulnerability vectors to check. The other scans work without it but do benefit from its context if present.