# Gimorra > Gimorra is an autonomous offensive-security agent. Point it at a target you are authorized to test and it runs recon → scan → propose a proof of concept → prove it deterministically → report. Non-AI guardrails make the autonomy safe: an in-loop scope guard, a non-destructive proof engine, a cleanup ledger and a kill switch. Human supervision is a dial instead of a check on every action. The same file is served at `/llms.txt` on the landing page, the demo console and the hosted console. It is the entry point for agents. Read these rules before you act on anything here: - **Authorized targets only.** Gimorra refuses active work when the run has no valid authorization artifact. Never point it at a system you do not have permission to test. - **It runs on the host that starts it.** The agent's shell and every security tool it calls run as the invoking user. Gimorra ships no sandbox. The real boundary is the environment you start it in: a VM, a container or a disposable machine. - **The defaults are permissive by design.** By default `agent.autonomy` is `unrestricted`, which means no approval gates. Each engagement's spend ceiling defaults to its intensity's figure (`$150` at `balanced`). Use `--autonomy strict` or `--autonomy standard` and `--spend-cap-usd ` when the target or the budget is not yours. - **The CLI is the interface.** `-j` / `--json` writes machine-readable JSON to stdout. Logs go to stderr. ## Agent quickstart: scan a live target For an agent testing a running application, host or domain it is authorized to test. ```sh gimorra scan -t https://app.example.com --intensity lite --spend-cap-usd 25 --detach # queues it, returns at once gimorra queue # what is queued, running and stopped gimorra eng list # every engagement with its full id gimorra eng brief # the confirmed findings, the open high+ leads and where the files are ``` - Install with the audit quickstart's line below, without `-s -- --for audit`: that readies the host for scans, installs the scan engine and ends with `gimorra setup --yes`. - `--detach` hands the scan to a background daemon and starts one if none is running, so a shell with a time cap is not tied to a run that outlasts one command. Without it the scan runs in the foreground until it ends. - `--intensity passive|lite|balanced|aggressive` sets how hard it pushes, with `balanced` as the default. `--spend-cap-usd` is the hard ceiling per engagement. Without it the intensity's own figure applies: `$60` at `lite`, `$150` at `balanced`. - `gimorra queue cancel ` stops a run and `gimorra queue resume ` picks a stopped one back up. - **Recon only:** `gimorra recon -t example.com` sweeps a domain for hosts and ranks what answers without scanning any of it. `gimorra scan -t example.com --roster board` scans the best of that ranking later. - **A brief, credentials included:** `gimorra scan -t https://app.example.com -p "test it logged in, username: qa@example.com password: "`. `-p` derives flags from the prose and keeps it as the run's brief; add `--dry-run` to read the derivation first. - Every scan flag, intensity and scope rung: `gimorra skills get gimorra-scanner --file references/scanning.md`. ## Agent quickstart: audit the repository you are in For a coding agent in a cloud sandbox (Claude Code on the web, or any session whose shell commands are time-capped). - **Install it in the environment's setup script**, which runs before the session starts. A running agent in auto mode is refused a downloaded script piped into `bash`, so an agent cannot install gimorra on its own mid-session; there the operator approves the install line, or runs it themselves. Environment variables are not set while an environment setup script runs, so the credential is checked at the first `gimorra` command, not during install. - **The credential**: a Claude Code cloud session's shell already carries the session's Claude routing (`ANTHROPIC_BASE_URL` and the `CLAUDE_CODE_*` variables), and gimorra's runs inherit it - nothing to set. Anywhere else, put `CLAUDE_CODE_OAUTH_TOKEN` (from `claude setup-token`) or `ANTHROPIC_API_KEY` in the environment's variables. - **The network**: these hosts must be reachable. An environment whose network policy blocks one adds it under a Custom network policy; `gimorra setup` names a host a policy refused (from the `x-deny-reason` header, where the policy sends one). - `cdn.vigolium.com` (the release download) - `gimorra.j3ssie.workers.dev` (the landing page, which serves this file) - `api.osv.dev` and `services.nvd.nist.gov` (the dependency pass's advisory lookups; without them that phase records what it could not check) ```sh curl -fsSL | bash -s -- --for audit gimorra audit . --mode deep --detach -b 25 # returns at once with the audit id gimorra audit status --wait 540 # blocks up to 9 minutes; repeat until the run ends gimorra audit show # the findings and the run's index document ``` - The first line is the setup script's; the rest are the agent's. `--for audit` readies the host for a source audit only: the audit tools, and no scan engine. If setup reports the host is not ready, run `gimorra setup --yes --for audit`. It repairs what it can and names the one step left. - `--detach` and `status --wait` are the shape for a shell with a time cap. A deep audit runs far longer than one command may, so the agent starts it in the background and polls. `status` exits `0` while the run is healthy and `2` when it failed or was stopped. - `-b ` is the run's spend ceiling, and it is recommended. A phase is not started once the budget is gone. Without it, an audit has no ceiling. - Every audit flag, mode and output file: `gimorra skills get gimorra-scanner --file references/audit.md`. - Audit a repository the session already has checked out. A sandbox's git proxy serves only the repositories attached to the session. ## Install The install line is invite-only during the alpha: contact jessie@vigolium.com for the demo, and the invitation carries the URL that replaces `` above. Once installed: ```sh gimorra setup --yes --for audit # repair what is missing and name the one step left (--for scan is the default) gimorra doctor # the read-only environment report ``` The audit quickstart's install line, without `-s -- --for audit`, readies a host for scans instead. The installer detects darwin/linux on arm64/x64, verifies the release with sha256, puts `gimorra` on PATH, installs the scan engine a scan requires, and ends by running `gimorra setup --yes`. Arguments go after `bash -s --`: `--for scan|audit|browser|all`, `--path `, `--prefetch` (also download what a run would fetch later), `--skip-engine` and `--version `. ## Connect a model Nothing to set when the Claude CLI is logged in or you are in a Claude Code cloud session. Otherwise set one of these, then run `gimorra doctor llm`: ```sh export CLAUDE_CODE_OAUTH_TOKEN= # a Claude subscription: `claude setup-token` prints one export GIMORRA_LLM_BASE_URL=http://127.0.0.1:8317 # any Anthropic/OpenAI-compatible endpoint, no trailing /v1 export GIMORRA_LLM_API_KEY=sk-xxxxxxxxxxxxxxxx export GIMORRA_LLM_MODEL=your-model-id ``` ## Drive it from a coding agent The binary carries its own manual as skills, so an agent queries the installed version instead of guessing flags. Read the one reference a task needs. `--full` prints every reference, more than 400 KB, which is too much for one context. ```sh gimorra skills # the bundled skills and their reference counts gimorra skills get gimorra-scanner # the driving skill: the CLI, recipes and a map of its references gimorra skills get gimorra-scanner --file references/scanning.md # one reference, raw: `gimorra scan` in full gimorra skills get gimorra-scanner --file references/audit.md # `gimorra audit` in full gimorra skills get gimorra-scanner --file references/agent-loop.md # the agent loop: what to run, poll and read gimorra skills get gimorra-scanner --file references/json-contracts.md # every --json shape, stream and exit code gimorra skills install -g # install them into ~/.claude/skills/ (--agent agents for agentskills.io agents) ``` The `gimorra-scanner` skill teaches an agent the whole CLI: scanning, proving, triage, reports and where a run writes its files. `gmr-deep-dive` turns a finished run into a hand-driven pentest. ## Core commands - `gimorra scan -t `: one-shot scan of a URL, host, domain, IP, CIDR, repo or app bundle. `--intensity passive|lite|balanced|aggressive` sets aggressiveness, with `balanced` as the default. - `gimorra -p ""`: start a scan from a prose brief. - `gimorra recon `: sweep a domain for hosts and rank them without starting a scan. - `gimorra audit `: multi-phase source-code security audit. - `--output ./out --report-html ./out/report.html` (on `scan` and `audit`): mirror the run's results into `./out` and write the full HTML report under the name you choose. - `gimorra eng [id]`: the read surface for a run: findings, jobs, scope, proof chain and transcripts. - `gimorra eng kill `: the kill switch. It stops new target traffic and rejects late proof commits. - `gimorra findings report `: render the engagement report. - `gimorra findings chain `: verify the hash-chained proof trail. - `gimorra serve`: the local gateway, with the operator dashboard at `/` and REST + SSE under `/api`. - `gimorra arsenal`: list the skills, tools, validators, vulnerability classes and scan phases this install has. `scan` is the default command, and every command takes `-h` for its flags and examples. In CI, `--exit-on-findings` exits `3` when a run finds anything actionable. Gimorra is crafted with <3 by [@j3ssie](https://github.com/j3ssie) --- # `gimorra scan` - test a live target One command from a bare target to a proved, reported finding. It creates and authorizes an engagement, drives a goal supervisor over it, proves every candidate with the deterministic proof engine, and writes the report. `scan` is the default command: `gimorra -p ""` runs `gimorra scan -p ""`. Write the verb out in scripts. ``` gimorra scan [options] [target] ``` The positional (or `-t/--target`, repeatable - one run per target) is auto-detected: | You pass | It becomes | | ---------------------------------------- | ------------------------------------------------------------ | | `https://app.example.com/item?id=1` | a URL entrypoint, scoped to that host alone | | `app.example.com` | a host, scoped to that name alone | | `example.com` (the registrable domain) | the apex and every subdomain | | `10.0.0.5` / `10.0.0.0/24` | a network engagement | | `./repo` / `https://github.com/acme/app` | a source-code audit, no network target | | `./openapi.json` / `./scope.csv` | an input the run was handed: a spec becomes testable surface | A URL or a subdomain buys that host and nothing beside it; only a bare apex compiles to a whole domain. `--scope typed|direct|apex|related` (default `apex`) decides which discovered hosts are admitted, and `--deny ` keeps one in the program but refuses every request to it. ```sh gimorra scan -t https://app.example.com # balanced, the default dial gimorra scan -t https://app.example.com --intensity lite -b 20 # lighter, with a $20 pool gimorra scan -t example.com --deny legacy.example.com # the apex, one host fenced off gimorra scan -T targets.txt --intensity lite # one engagement per line gimorra scan -t https://app.example.com --detach # hand it to the background daemon ``` ## Intensity and spend `--intensity passive|lite|balanced|aggressive` is the one dial most runs need: it moves the phases that run, the child spend pool and the supervisor's turn cap together. `-b/--budget-usd` sets the run's pool outright. `--spend-cap-usd` is the hard ceiling per engagement; with none typed the dial's figure applies (passive `$25`, lite `$60`, balanced `$150`, aggressive `$400`), and `--spend-cap-usd 0` is no cap. ## Briefs: `-p` and `-P` `-p ""` is what to do, in your own words. The run reads it three ways: it derives flags from it (each printed with the words behind it), opens any file or folder it names, and keeps it as the engagement's brief. `-P ` reads the brief from a file - a handover rather than a sentence. The whole file becomes the brief; it gives up its target, and its paragraphs set no flags unless `--prompt-flags` is typed, so put the flags on the command line beside it. Add `--dry-run` to read the derivation before anything spends. ```sh # Focus the run gimorra scan -t https://app.example.com -p "focus on IDOR and broken access control" # A carve-out: lands as --deny admin.example.com, plus --intensity aggressive gimorra scan -t example.com -p "but not admin.example.com, be aggressive" # Credentials in the brief: they reach the run as the brief, and a username is never read as a target gimorra scan -t https://app.example.com -p "test it logged in, username: qa@example.com password: Qa-Test-2026" # A login you recorded yourself: a HAR path in the brief is filed as the run's session gimorra scan -t https://app.example.com -p "I recorded the login session in this HAR file ./alice.har" # A handover file - test accounts, rules of engagement - kept out of shell history; flags on the line gimorra scan -P ./brief.md --intensity aggressive # Read the derivation, spend nothing gimorra scan -t https://app.example.com -p "go deep on the API, report as html" --dry-run ``` A brief can widen the ask and never the guardrails: `--credential-test` (default-credential attempts, spraying), `--state-change` and `--own-writes` are off unless typed, at every intensity, and no sentence turns them on. A sentence that names no concrete host fails closed - nothing is scanned. Prose carve-outs work only through `-p`; in the positional a named host is read as another target. ## Logged-in testing: accounts the proof engine replays A brief gets credentials to the supervisor. These flags file each account as a principal (`principal[:tenant[:privilege]]`) the proof engine replays, so a finding behind a login is proved rather than left `open`. Two accounts make the two-principal authorization tests possible. ```sh gimorra scan -t https://app.example.com --session-from alice:acme:user=./alice.har # a login you recorded (HAR, Caido, Burp export) gimorra scan -t https://app.example.com --account 'bob:acme:admin=cookie:sid:env:BOB_SID' # a cookie, read from an env var gimorra scan -t https://app.example.com --auth-file ./sessions.yaml # headers or a login flow per session gimorra scan -t https://app.example.com --header 'X-Bug-Bounty: ' # a header on every request gimorra eng login # log in yourself; renews an expired session ``` An `--account` value is always a reference (`env:VAR` or `@file`), never the secret itself. A recorded session cannot be renewed by the run: when it expires, `gimorra eng login` records a fresh one. ## Following a run ```sh gimorra queue # what is queued, running and stopped gimorra eng brief # confirmed findings, the open high+ leads, where the files are gimorra findings report -f html -o report.html gimorra eng kill # the kill switch: no new target traffic, late proofs rejected gimorra queue resume # pick a stopped run back up ``` Every scan flag, intensity and scope rung: `gimorra skills get gimorra-scanner --file references/scanning.md`. ## `gimorra recon` - map the hosts, scan later Recon only: sweep a domain for hosts, probe and rank what answers, and start nothing - no engagement, no scan. The ranking is kept on the apex's target board, so a later scan reads it instead of sweeping again. ```sh gimorra recon -t example.com # deep: every discovery leg, permutations, a model judge gimorra recon -t example.com --recon-level basic # the two default datasets, no guessing gimorra recon -t example.com --intensity passive # third-party traffic only, nothing sent to the hosts gimorra recon -t example.com -p "payments and admin panels first" # orders the ranking, widens nothing gimorra recon -T apexes.txt -R 0 -b 10 # every domain in a file, no ranking ceiling, $10 of model spend gimorra targets example.com --hosts --status 200 # read the boarded roster back gimorra scan -t example.com --roster board # scan the best 75, one engagement per host ``` A recon `-p` is context for the ranking's order only: it names no targets and sets no flags. `--no-agent` is the tokenless sweep, `--ports-sweep` and `--asn-sweep` opt in to port and address-range legs, and `--deny` keeps a host out of the sweep entirely. # `gimorra audit` - source-code security audit A whitebox audit of a repo or directory, with no live target. It drives a multi-phase agent pipeline, records the run in the store (`gimorra audit ls`), and keeps its results in the engagement folder like any other run. The full reference - every flag, the re-entry table, the JSON keys - is `gimorra skills get gimorra-scanner --file references/audit.md`. ``` gimorra audit [options] [source] gimorra audit ls | coverage | status | show | resume | stop | salvage | gate | poc | verify [run] ``` ```bash gimorra audit . # balanced (the default), the current repo gimorra audit . --mode deep -b 40 # the full audit, with a spend ceiling gimorra audit . --mode deep --detach -b 40 # the same, in the background - returns at once gimorra audit status --wait 540 # follow it (bounded): phase lines, heartbeat, then the report gimorra audit -s https://github.com/acme/app # clone + audit gimorra audit ./repo --mode lite # the cheap pass gimorra audit . --mode deep --dry-run # what would run here and what skips, spending nothing ``` A remote git URL is cloned first, unless the current directory is a checkout of that repository, which is then read in place. In a Claude Code cloud session that is the only path that works: its GitHub proxy serves only the repositories attached to the session. ## One message, in a cloud session ```bash gimorra audit --mode deep --dry-run --fix # readiness, and the one setup line it names gimorra audit --mode deep -b --llm-model-fallback \ --report-html ./out/report.html --detach # prints {engagement, auditId, ...} and returns gimorra audit status --wait 6600 # run it as a BACKGROUND tool call, re-armed before it expires gimorra audit show --bundle ./out/deliverable.zip # the masked hand-over, once the run has ended ``` - **Keep-alive.** `status --wait` prints one stderr line per phase change and a heartbeat every 60 s. Keep one running for the whole audit; never replace it with a scheduled check-in, because an idle container is reclaimed, and the run with it. - **Recovery after a reclaim.** Re-run the launch line, or `gimorra audit resume --detach`. The engine knows what is left. - **Publish `./out/report.html` unchanged** as the artifact. It is gimorra's report - phase table, served models, findings, coverage. - **A refusal.** `⊘ model refusal [cyber] · served by ` needs nothing: the provider re-served the session and it carried on. `⊘ refused … nothing was served` is rerouted to the model the provider already re-served this run on, else `--llm-model-fallback `. Never reword a prompt to get past a safeguard. ## Modes `-m/--mode` picks the phase graph. With no `--mode`, `--intensity` picks it: `passive`/`lite` → `lite`, `balanced` → `balanced`, `aggressive` → `deep`; with neither the mode is `balanced`. _Generated:_ | Mode | Phases | Confirms by default | `--deps` | `--experiments` | What it is | |---|---|---|---|---|---| | `lite` | 6 | no | off | off | Discovery and attack-surface mapping first - recon, then every request-handling boundary of the tree mapped into a machine-readable entry-point inventory with its guards and pre-auth classification - then a secrets scan and a fast SAST pass in parallel, then PoC authoring. | | `balanced` | 13 | no | advisories | off | Source audit - advisory intelligence and an entry-point inventory of every request-handling boundary in parallel, threat model, intent cartography, SAST and a single probe team, one review chamber with FP elimination, intent reconciliation, PoCs with a reproduction review and a composed report. | | `deep` | 21 | yes | fetch | sandbox | Full multi-phase security audit - advisory intelligence, commit archaeology, an entry-point inventory of every request-handling boundary, patch-bypass analysis, threat model, intent cartography, SAST with structural extraction, deep probe teams, an exhaustive authorization audit that verifies every guard at the handler and deepens the inventory it reads, review chambers with inline cross-service taint and variant expansion, FP elimination, a reach assessment, intent reconciliation, PoCs with a reproduction review, patches under --patch and a composed report. | | `knowledge-base` | 4 | no | off | off | Build a reusable, source-grounded application knowledge base and attack-surface model - advisory intelligence and an SBOM, a machine-readable entry-point inventory of every request-handling boundary with its guards and pre-auth classification, and the architecture and threat model over them. | | `diff` | 1 | no | off | off | Incremental audit over the changes since the last audited commit - risk-classify the diff, then re-run only the phases the changed surface warrants. | | `confirm` | 9 | yes | off | off | Run a confirmation pass for existing confirmed or theoretical findings that boots the target application (or connects to a remote target), executes existing PoC scripts against it, falls back to generated test cases for findings the PoC could not reproduce, and produces a confirmation report with per-finding verdicts. | | `reinvest` | 3 | no | off | off | Cross-agent reinvest - re-verify a prior audit's CRITICAL and HIGH findings on a DIFFERENT model than produced them, to surface model-specific blind spots. | | `longshot` | 25 | yes | fetch | sandbox | Bottom-up hunt over the attack surface. | | `deep-flat` | 24 | yes | fetch | sandbox | Deep's full intelligence pipeline - advisory intelligence, commit archaeology, an entry-point inventory, patch-bypass analysis, threat model, SAST with structural extraction, an exhaustive authorization audit and the specialist passes - with a flat hunt and a flat contest in place of deep's probe teams and review chambers - one selector session per lens, one prober session per admitted hypothesis, then every draft judged, reproduced, cold-verified, adjudicated and weighed for reach one session each - followed by intent reconciliation, PoCs and a composed report. | ## Run verbs _Generated:_ | Command | What it does | |---|---| | `gimorra audit ls` (--source , --limit ) | list recorded audit runs - newest first; --source narrows to one source | | `gimorra audit coverage [run]` | what every earlier run of a source covered, cut and left open - entry points never swept, units with leads, lens yield, drafts the contest removed, leads nobody worked; the round steerer's brief (default: the source in the current directory) | | `gimorra audit status [run]` (--wait ) | a run's phases, findings so far, cost and the next command; --wait blocks until it ends, printing each phase change and a heartbeat a minute to stderr | | `gimorra audit show [run]` (--phase-prompt , --bundle , --with-analysis, --finding , --deployment ) | a run's findings and its index document (INDEX: the run's README.md); -f html\|md -o writes the run's report | | `gimorra audit resume [run]` (--phase , --hypotheses , --sweep , -b, --budget-usd , -d, --detach, --take-over, --stream , --no-clip, --quiet-commands) | continue the newest unfinished run of this source (or the one named) with its saved dials; --llm-model / --llm-model-fallback typed here outrank the saved ones | | `gimorra audit stop [run]` (--wait , --kill) | stop a running audit - its phases settle, its record ends `aborted`, and it stays resumable; says whether the request landed and which pid owns the pass | | `gimorra audit salvage [run]` (--apply) | list the file writes the run's sessions made that never landed (a denied Write, a call cut off) whose target is a declared output and not on disk, read back whole from the recorded console; --apply writes them where nothing exists | | `gimorra audit gate [run]` (--phase , --all, --dir , --explain, --floor ) | evaluate a phase's completion gate against the run directory now; --explain lists every condition with what it found, including glob matches not counted (stale, unselected); --all evaluates every phase and the PoC contract of every finding, --dir any run directory on disk | | `gimorra audit poc [run]` (--finding , --target , --run) | print one finding's runbook with its placeholders filled from --target and the identities a confirmation pass seeded; --run fires it at --target from a one-shot isolated executor and prints what came back beside the Expected line | | `gimorra audit verify [run]` (--finding , --target , --confirm-exec ) | confirm ONE finding the way a confirmation pass does - its plan, the harness first, the runbook against --target, the browser beside it - writing the same Confirm-* keys and store verdict, and no confirmation report | A run is named by its audit id (any unique prefix), its engagement id, its run directory, or a source; with nothing named, the newest run of the source in the current directory. Running `gimorra audit ` again re-enters that source's last run: it resumes a stopped one, shows a finished one, or audits only what changed since it. ## The flags most runs need - `-b, --budget-usd ` - the whole-run ceiling, checked between phases. Without it an audit has no ceiling. - `-p, --prompt ` / `-P, --prompt-file ` - the operator's brief, read verbatim by every phase; every file or folder it names is read as knowledge. - `--confirm` / `--no-confirm` - the confirmation pass that boots the app and runs the PoCs. On by default for `deep`, `deep-flat` and `longshot`. `-t, --target ` confirms against an app that is already running. - `--skip ` - phase ids to decline (`D2,D3`); a value naming no phase is refused. - `--detach`, `--report-html `, `--output ` - background run, the HTML report, the results mirror. - `--llm-model `, `--llm-model-fallback `, `-L, --llm-profile ` - what serves the phases. ## Confirming findings A plain audit records static leads. A confirmation pass executes each finding's PoC against the running app and projects the verdict onto the store: `live-verified` and `test-verified` become `confirmed`, `false-positive` stays one, `not-reproduced` becomes `ruled-out`. ```bash gimorra audit ./repo --mode deep --target http://127.0.0.1:3000 # verify against a running app gimorra audit ./repo --mode deep # build & boot from source, in a container gimorra audit show --finding H2 # one finding's whole trail gimorra audit poc --finding H2 --target http://127.0.0.1:3000 --run # fire its runbook gimorra audit verify --finding H2 # a confirmation pass narrowed to H2 ``` To audit source and test the running app in one engagement, use `gimorra scan -t https://staging.example.com --source ./repo`. Reading the code never settles a finding; the proof engine is the only thing that confirms. ## Reading a run 1. `gimorra audit show ` (or the run's `README.md`) - every phase and how it ended, the attack surface, the findings and the filtered drafts; 2. `final-audit-report.md` - the composed narrative, model-written; 3. a finding's `report.md` under `findings/-/` (evidence-backed) or `findings-theoretical/-/` (unproven), with its `VERIFY.md` and `poc/`; 4. `gimorra audit status --json` for scripts. Every audit mirrors into a results folder: `gmr-audit/` inside the audited directory for a local source, else `./gmr-audit//`, one folder per run under `runs//`. Exit codes: 0 a complete run; 2 a run that is not `complete`, or a confirmation pass that failed; 1 a refusal before anything started.