OpenGhost

Agent Skill for authorized web application and supporting server integrity penetration testing.

OpenGhost helps an AI coding agent run a scoped security assessment. The agent plans the work, tests carefully, validates evidence, and writes findings. OpenGhost provides the Docker sandbox, scope files, evidence folders, reusable checks, and report templates.

OpenGhost is fully local and open source. It has no hosted service, account, API key, telemetry requirement, or managed control plane.

[!IMPORTANT] Use OpenGhost only on systems you are explicitly authorized to test.

Write the allowed targets, exclusions, accounts, rate limits, test windows, emergency contacts, and rules of engagement into the generated scope file before active testing.

How to Use

Install the skill with the skills CLI:

npx skills@latest add https://github.com/VAIBHAVSING/openghost --skill openghost-skill

Then ask your agent to use OpenGhost for an authorized assessment:

Use $openghost-skill to assess https://target.example.
Authorization and scope details are in the engagement notes.

Make sure Docker is running and Bash 4.3+ plus Python 3 are available. Security tools are executed through the OpenGhost sandbox, not directly on your host machine.

git clone https://github.com/VAIBHAVSING/openghost.git
cd openghost
export PATH="$PWD/skills:$PWD/skills/openghost-skill:$PATH"
openghost help

git clone https://github.com/VAIBHAVSING/openghost.git /tmp/openghost
mkdir -p ~/.agents/skills
cp -R /tmp/openghost/skills/openghost-skill ~/.agents/skills/

Start an Engagement

Create a scoped workspace before testing:

openghost sandbox start
openghost engagement init --url https://target.example --name target-example
export OPENGHOST_SCOPE=.openghost/engagements/target-example/scope.yaml
# Edit scope.yaml, set authorization.reviewed: true, then validate it.
openghost scope validate

Edit the generated scope file:

.openghost/engagements/target-example/scope.yaml

Add the allowed hosts, ports, paths, accounts, roles, tenants, exclusions, rate limits, test windows, destructive-test rules, emergency contacts, and notes.

OpenGhost keeps generated engagement data under .openghost/. That data is operational evidence and should normally stay out of commits.

What OpenGhost Includes

OpenGhost
|-- Agent Skill instructions
|-- Docker sandbox launcher
|-- Engagement state and scope helpers
|-- Evidence, finding, and report helpers
|-- Reusable assessment scripts
`-- Reference modules for common web and API test areas

Assessment Modules

OpenGhost is one skill package with several focused modules. The agent loads the deeper reference only when that topic is needed.

Basic Workflow

Run safe checks through the sandbox:

openghost sandbox status
openghost script list
openghost script run web-baseline -- --target-url https://target.example
openghost script run api-inventory -- --target-url https://target.example

Record evidence:

openghost evidence add --path response.txt --kind response --title "Baseline response" --redaction redacted

Save a confirmed finding:

openghost finding add \
  --title "Example finding title" \
  --severity medium \
  --priority P3 \
  --module server-integrity \
  --url "https://target.example/" \
  --confidence 95 \
  --evidence E-001 \
  --step "Captured the baseline response." \
  --impact "Documented confirmed behavior." \
  --priority-rationale "P3 because impact is limited." \
  --remediation "Apply the recommended hardening."

Generate the report:

openghost context show
openghost coverage set --module server-integrity --status tested
openghost evidence verify
openghost report validate
openghost report generate

Common Commands

Sandbox

openghost sandbox start
openghost sandbox status
openghost sandbox stop
openghost sandbox update
openghost sandbox shell

Tool Execution

openghost run <tool> [args...]
openghost bash '<command>'
openghost python code '<script>'
openghost python file <path> -- [args...]

ZAP and Browser Workflows

openghost zap start
openghost zap baseline --target https://target.example --minutes 5
openghost zap api-scan --target https://target.example/openapi.json --format openapi --target-url https://target.example
openghost zap alerts --format md
openghost browser devtools --url https://target.example --zap

Engagement Helpers

openghost todo add --task "Complete surface mapping" --module surface-map --priority high
openghost evidence add --path <file> --kind <kind> --title <title> --redaction <raw|redacted|sanitized>
openghost artifact add --path <file> --kind <kind> --title <title>
openghost finding add --title <title> --severity <severity> --module <module> --url <url> --confidence <90-100> --evidence E-001
openghost coverage set --module <module> --status <status>
openghost evidence verify
openghost report validate
openghost report generate

Script Templates

openghost script list
openghost script show api-inventory
openghost script copy xss-check
openghost script run cors-check -- --base-url https://target.example --endpoints /api/me /

Safety Model

• Confirm authorization, targets, exclusions, rate limits, and test windows before testing.
• Set OPENGHOST_SCOPE and verify scope before each target, module, and tool run.
• Run security tooling through openghost, not directly on the host.
• Treat scanner output as leads until validated with evidence.
• Keep generated engagement data under .openghost/ and normally out of commits.
• Use destructive, high-volume, or state-changing checks only when the rules of engagement explicitly allow them.
• Separate confirmed findings from notes, draft leads, and speculation.

Repository Map

.
|-- README.md
|-- ARCHITECTURE.md
|-- DEVELOPMENT.md
|-- AGENTS.md
|-- CONTRIBUTING.md
|-- SECURITY.md
|-- Dockerfile
|-- docker/
|-- openghost
`-- skills/
    |-- openghost
    `-- openghost-skill/
        |-- SKILL.md
        |-- agents/
        |-- assets/
        |-- openghost
        |-- references/
        |   `-- modules/
        `-- scripts/
            `-- pentest/

Developer Docs

• Architecture - components, command flow, trust boundaries, and engagement state.
• Development - local setup, validation commands, and release checklist.
• AGENTS.md - coding-agent maintenance context.
• Contributing - contribution rules and pull request expectations.
• Security - vulnerability reporting policy.
• Attribution - attribution and provenance notes.

Contribute

Keep OpenGhost direct and practical:

• Keep README.md simple: purpose, install, basic use, safety, and repo map.
• Keep detailed methodology in skills/openghost-skill/SKILL.md and skills/openghost-skill/references/.
• Keep security tools inside the Docker sandbox.
• Keep examples scoped and non-destructive.
• Keep confirmed findings evidence-backed.

License

OpenGhost is licensed under the Apache License 2.0. See LICENSE.