GeistScope Tool Suite — Overview

What this is

GeistScope is a Rust-based bug bounty and red-team toolchain built around one shared engagement workspace. Every binary writes to the same directory layout so the human operator, the CLI tools, the TUI, and an AI assistant can read and write the same files. The directory layout is the contract.

Each tool has its own wiki page — pick one from the sidebar.

The product layer is a TUI-based bug-hunting browser backed by a scoped AI harness. The AI never gets raw shell access; it calls typed tool endpoints through mg-harness, which enforces scope, redaction, risk class, and audit logging before anything runs. mg-harness chat <engagement> opens an interactive coding-agent REPL bound to one engagement, with backends for Ollama (local), any OpenAI-compatible HTTP server, or Anthropic — see mg-harness.

Workspace layout

Every target starts with mg-engagement init. That creates:

engagements/<name>/
|-- engagement.json
|-- scope.json
|-- notes.md
|-- audit.log
|-- recon/
|   |-- subdomain-enum.json
|   |-- fingerprint.json
|   |-- mg-scan.json
|   |-- summary.json
|   |-- probe-report.json
|   |-- priorities.md
|   |-- priorities.json
|   |-- chain-analysis.md
|   |-- chain-analysis.json
|   `-- fuzz-<timestamp>.json
|-- crawl/<host>/
|   |-- pages/
|   |-- js/
|   |-- index.json
|   |-- endpoints.json
|   |-- secrets.json
|   |-- internal-refs.json
|   |-- vulnerable-libraries.json
|   |-- graphql-candidates.json
|   `-- graphql-schema.json
|-- findings/
|   |-- <id>-<slug>.md
|   |-- <id>-<slug>-report.md
|   |-- <id>-<slug>-cve.md
|   |-- <id>-<slug>-disclosure.eml
|   `-- <id>-<slug>-replay-<date>.json
|-- re/<binary>/
|   |-- manifest.json
|   |-- raw/<func>.c
|   |-- <func>.md
|   `-- <func>.json
|-- aifuzz/
|   |-- CONSENT
|   |-- sentinels.txt
|   `-- <run-id>.jsonl
`-- exploits/<cve>/
    |-- Cargo.toml
    |-- runbook.md
    |-- src/
    `-- tests/smoke.rs

scope.json is default-deny. Active tools check the scope before touching any target.

Product direction

TUI browser
  -> local AI harness
       -> scoped Rust tool endpoints
            -> engagement workspace

The CLIs stay useful standalone. The harness is the safe adapter between an AI API and the tools: strict schemas, narrow allowed tools, scope checks before active traffic, bounded output capture, and redaction before model-visible context. See mg-harness for the endpoint contract.

Typical workflow

# Create and scope
mg-engagement init acme-bounty --target acme.example.com --platform hackerone
mg-engagement scope-add acme-bounty "*.acme.example.com"
mg-engagement scope-deny acme-bounty "*.dev.acme.example.com"

# Recon
mg-recon acme-bounty --ports 1-1024 --concurrency 100
mg-crawl acme-bounty https://www.acme.example.com https://api.acme.example.com

# Prioritize
ai-prioritize acme-bounty

# Posture and active checks
mg-probe acme-bounty --active

# Fuzz, replay
mg-fuzz acme-bounty --template idor.txt --payloads numbers:1-200 --mode sniper
mg-replay acme-bounty 20260514-probe-001

# Report and disclose
mg-report generate acme-bounty 20260514-probe-001
mg-report disclose acme-bounty 20260514-probe-001 \
    --vendor "Acme Corp" --contact [email protected]

Additional tools

Analysis and exploit dev: mg-recopilot, mg-aifuzz, mg-exploitgen, mg-report

Recon expansion: mg-whois, mg-shodan, mg-dns-enum, mg-dns-history, mg-cloud-enum, mg-cname-chain, mg-udp-scan, mg-takeover, mg-vhost

OSINT: mg-github, mg-breach, mg-google-dork, mg-leak-monitor

Web vulnerability scanning: mg-webscan — XSS, SQLi, SSRF, SSTI, XXE, traversal, open redirect, CSRF, command injection, CORS, cache poisoning, prototype pollution, deserialization, and request smuggling

Auth and session: mg-jwt, mg-authz, mg-oauth, mg-session-audit, mg-brute

OOB and cloud metadata: mg-oob, mg-aws, mg-gcp, mg-azure, mg-serverless, mg-k8s, mg-docker

Network services: mg-tls-scan, mg-ssh-audit, mg-smtp, mg-snmp, mg-smb, mg-http2

API surface: mg-graphql, mg-openapi, mg-grpc, mg-websocket

Mobile and static analysis: mg-artifact-audit, mg-secret-validate, mg-csp

Post-access: mg-privesc-linux, mg-privesc-windows, mg-loot

Workflow: mg-diff, mg-notify, mg-timeline, mg-dns-rebind

Build and install

cd crates
cargo build --workspace
cargo test --workspace
cargo clippy --workspace -- -D warnings

# Install all binaries
cargo install --path engagement
for crate in subdomain-enum mg-scan fingerprint mg-recon corpus-builder \
             mg-crawl mg-probe mg-fuzz mg-replay mg-tui mg-harness mg-report \
             mg-recopilot mg-aifuzz mg-exploitgen \
             mg-whois mg-shodan mg-dns-enum mg-dns-history mg-cloud-enum \
             mg-cname-chain mg-udp-scan mg-takeover mg-vhost \
             mg-github mg-breach mg-google-dork \
             mg-leak-monitor mg-webscan mg-jwt mg-authz \
             mg-oauth mg-session-audit mg-brute mg-oob \
             mg-aws mg-gcp mg-azure mg-serverless mg-k8s mg-docker \
             mg-tls-scan mg-ssh-audit \
             mg-smtp mg-snmp mg-smb mg-http2 mg-graphql mg-openapi mg-grpc \
             mg-websocket mg-artifact-audit \
             mg-secret-validate mg-csp mg-privesc-linux mg-privesc-windows \
             mg-loot mg-diff mg-notify mg-timeline \
             mg-dns-rebind; do
    cargo install --path "$crate"
done

Docker

A multi-stage Dockerfile ships all 63 workspace binaries in one debian:bookworm-slim runtime image. CI publishes it to ghcr.io/machinageist/geistscope on every push to main and on tagged releases. Mount a host directory at /workspace/engagements to persist findings between runs.

docker pull ghcr.io/machinageist/geistscope:latest

# Single-shot endpoint dispatch
echo '{"endpoint":"endpoint.registry","engagement":"foo"}' | \
  docker run --rm -i -v "$PWD/engagements:/workspace/engagements" \
    ghcr.io/machinageist/geistscope:latest dispatch

# Chat REPL against a local Ollama on the host
docker run --rm -it --network host \
  -v "$PWD/engagements:/workspace/engagements" \
  ghcr.io/machinageist/geistscope:latest chat my-engagement \
  --backend ollama --model qwen2.5-coder

Source repo

github.com/machinageist/geistscope. Continuous integration runs build / clippy / cargo test / cargo-audit / integration smoke against a deliberately-vulnerable Docker target. Tagged releases produce Linux x86_64 and macOS (Intel + Apple Silicon) binary tarballs alongside the container image.