# Gimorra

> Gimorra is an autonomous offensive-security CLI, part of Vigolium (https://www.vigolium.com/). Point it at a target you are authorized to test and it runs recon → scan → propose a proof of concept → deterministically prove → report. It comes back with the bug reproduced. Status: early alpha demo (v0.1.67-alpha); expect rough edges and breaking changes between releases.

Only ever point Gimorra at systems you are authorized to test. No authorization artifact, no active operation: that is enforced in code.

## Install (alpha)

The public installer is not released yet; the install link is coming soon.

Once installed, agent runs authenticate through the Claude Code CLI login or `ANTHROPIC_API_KEY`.

```sh
gimorra doctor          # environment check (runtimes, docker, SDK auth)
gimorra doctor --fix    # install whatever it reports missing
```

## Usage

`gimorra scan` is the one-shot entry point. It auto-detects the target type (URL, host, domain, IP, CIDR, repo, spec or a prose brief), scopes and authorizes a fresh engagement, runs a vigolium discovery/DAST sweep, then drives a goal supervisor to completion. `--intensity` is the single dial: `passive | lite | balanced | aggressive` (default `balanced`).

```sh
gimorra scan acme.test                                   # a domain
gimorra scan 'http://127.0.0.1:3000/item?id=1'           # a URL with a query parameter
gimorra scan 10.0.0.0/24 --intensity lite                # a CIDR, lighter dial
gimorra scan -t acme.test -p "focus on IDOR and broken access control"
gimorra scan -T targets.txt                              # one target per line
gimorra scan api.acme.test --spec ./openapi.json         # API spec or captured traffic as surface
gimorra scan acme.test --source ./path/to/repo           # add a source-code audit phase
gimorra scan 'http://127.0.0.1:3000/item?id=1' --no-agent   # deterministic proof engine only, no tokens

gimorra findings <engagement-id>                         # read the results
gimorra findings <engagement-id> -f md                   # markdown report
gimorra findings chain <engagement-id>                   # verify the hash-chained proof trail
gimorra eng kill <engagement-id>                         # stop new traffic for an engagement
```

## How it works

Autonomy is bought with deterministic guardrails rather than a per-action human prompt. These controls contain no AI and hold even if the model is prompt-injected:

- Scope guard: deny wins, ambiguous input blocks. Checked on every tool call that names a target, before the autonomy policy is consulted.
- Authorization gate: no valid authorization artifact, no active operation; expiry and validity windows are checked.
- Proof engine: the agent proposes, deterministic code disposes. A candidate is re-proven host-side by the least invasive non-destructive proof. Only confirmed findings are stored; there are no self-certified findings.
- Cleanup ledger: every state change is recorded when authorized and undone at teardown, so an engagement cannot close dirty.
- Kill switch: `gimorra eng kill <id>` stops new traffic, including from a job already running. It does not recall a request already on the wire.

Orchestration: one goal in, specialist children out. Each child is a durable queue row with its own workdir and a SHA-pinned slice of the arsenal. Nothing a child returns is a finding until the proof engine re-proves it.

Evidence: one scan writes one engagement folder. A finding is its proof document, addressed by content SHA-256; the redacted copy is hash-chained, the raw copy is written 0600 and never hashed. On import the chain is recomputed against the manifest.

## Security posture

The default posture is unrestricted and unsandboxed on purpose: no approval gates, tools run on your host as your user, and token spend is unbounded unless you set `agent.spend_cap_usd`. The security boundary is the environment you run Gimorra in. Run it in a VM, a disposable box, or a container. The scope guard does not read targets out of shell command lines; those calls are allowed and recorded as `scope-unbounded` events.

```sh
gimorra config set agent.autonomy standard     # state-changing actions park for approval
gimorra scan acme.test --autonomy strict       # recon only, per run
gimorra config set agent.spend_cap_usd 50      # hard ceiling on engagement spend
```

## Pages

- [Home](https://gimorra-landing.j3ssie.workers.dev/): overview, controls, orchestration, a replayed run, and the evidence chain
- [Security posture](https://gimorra-landing.j3ssie.workers.dev/security): default posture, what the controls do not confine, how to sandbox a run, and how to report a vulnerability in Gimorra
- [Vigolium](https://www.vigolium.com/): the platform Gimorra belongs to