Augury is an agentic AI tool that produces high-level, organisation-specific cyber threat assessment reports on a recurring (typically annual) cadence, with human-in-the-loop review between phases. The output is a self-contained HTML + PDF report covering the organisation's profile, threat landscape, threat actors, specific threat scenarios with probability × impact ratings, and a change-analysis section comparing against any prior assessment.
This repository contains both the requirements specification
(augury_requirements_v0.10.md) and the running implementation.
Five minutes from a clean machine to a running instance.
Prerequisites: Docker Engine 20.10+ with the Compose v2 plugin
(docker compose version should return a v2.x version). On Linux:
sudo apt-get install docker-compose-plugin. On macOS/Windows: Docker
Desktop ships the plugin.
# 1. Clone the repo
git clone https://github.com/aschafs/augury.git
cd augury
# 2. Generate a master encryption key (one-time, never lose this)
KEY=$(docker run --rm python:3.12-slim sh -c \
"pip install --quiet cryptography && python -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())'")
# 3. Stash the key in a .env file (gitignored)
cp .env.example .env
sed "s|^AUGURY_SECRETS_KEY=.*|AUGURY_SECRETS_KEY=$KEY|" .env > .env.tmp && mv .env.tmp .env
# 4. Start it
docker compose up -d
# 5. Wait ~20s for the healthcheck, then open the UI
docker compose ps # should show "healthy"
open http://127.0.0.1:8080 # or browse to the URL manuallyOpen Settings → API keys in the UI and enter at least one LLM provider key (Anthropic, OpenAI, Gemini, …) and one search-provider key (Brave or Tavily recommended). Then click + New assessment on the dashboard.
A walkthrough of the first assessment, what each phase produces, and
how to interpret the report is in
src/augury/web/help_content/getting-started.md
(also served at http://127.0.0.1:8080/help/getting-started once the
server is up).
| Doc | When to read it |
|---|---|
| Installation guide | First-time setup, every variant (Docker Compose, plain Docker, source) |
| Operations guide | Day-2: start/stop/restart, upgrade, backup/restore, logs, master-key handling |
| Troubleshooting guide | "Something's broken" — symptom-keyed problem solving |
| In-app help | What the tool does — concepts, phase guide, report walkthrough, FAQ. Also served at /help once running |
| Requirements spec | What the tool is supposed to do and why |
The web app described above is the primary way to produce a report,
but the repo also ships a self-contained agentic skill at
.claude/skills/org-threat-report/
that runs the same five-phase, human-reviewed workflow without any of
the Python service, database, vault, or web UI.
The skill is loaded by an agentic CLI or IDE that supports the
Claude skill format
(Claude Code, the Claude desktop/web app, or any
Agent-SDK-based harness). Point your agent at this repository and ask
for an organisational threat report; the agent reads SKILL.md,
walks the same five phases with you (Profile → Landscape → Actors →
Threats → Change), and writes per-cycle artefacts, the threats
registry, and the rendered HTML/PDF report directly to disk under an
orgs/<org-slug>/ tree.
It is intentionally a thinner path: no encrypted vault, no audit log,
no provider-agnostic abstraction, no per-role model overrides — the
agent runs whichever model the host CLI is configured with, and the
phase prompts and rating scales live as plain markdown reference
files under
.claude/skills/org-threat-report/references/.
Reach for it when you want a one-off report on a laptop, when you
can't or don't want to stand up the server, or when you want to drive
the workflow from inside an editor session rather than a browser.
The full web app remains the right answer for recurring assessments,
multi-cycle trend analysis, and anything that needs the threat-ID
ledger to persist across runs with operational guarantees.
⚠️ Security is your responsibility. Augury has undergone basic security reviews, but is provided as-is, with no security warranty. Before pointing it at sensitive, confidential, or regulated documents, satisfy yourself — through your own security testing and review — that the deployment meets your requirements. You are responsible for the data you feed it and the providers you configure.
- Single-user, localhost-bound by default. No authentication, no
authorisation. Built for an individual analyst running it on their
own machine or a private VM. The HTTP port binds to
127.0.0.1by default; binding beyond loopback prints a warning at startup. - Provider-agnostic LLM and search. Anthropic, OpenAI, Gemini, Vertex AI, Ollama, vLLM, Brave, Tavily, SearXNG all supported via a thin abstraction layer. Switch providers from the Settings UI without restarting.
- Encrypted at rest secrets store. API keys entered via the UI are Fernet-encrypted using a master key supplied at startup. The encrypted vault lives in a separate directory from the main data store so routine backups can't accidentally include it.
- Local data only. No analytics, no telemetry, no third-party destinations except the LLM and search providers you configure. Uploaded documents, generated reports, and audit logs never leave the deployment.
- Human review between every phase. Five phases (Profile → Landscape → Actors → Threats → Change), each pausing for reviewer approval, edits, or revision before continuing.
# Working copy (Python 3.12 required)
python3.12 -m venv .venv
.venv/bin/pip install -e ".[dev]"
# Test suite
.venv/bin/pytest -q
# Run locally (without Docker) — see docs/installation.md for env setup.
# Foreground: handy for first-time bring-up so you see startup errors.
.venv/bin/python -m augury
# Or use the bundled control script for everyday dev (backgrounds the
# server, writes PID + log files, idempotent):
scripts/server.sh start # nohup-detach
scripts/server.sh status # PID, uptime, port-listening check
scripts/server.sh restart # required after any edit under src/
scripts/server.sh stopCode changes under src/ only take effect after a restart — the
server doesn't hot-reload modules. Settings changed via the UI
(API keys, LLM model overrides, etc.) hot-reload at runtime and
don't need a restart.
PolyForm Noncommercial License 1.0.0 — full text in
LICENSE, canonical version at
https://polyformproject.org/licenses/noncommercial/1.0.0.
Plain-English summary (not legal advice — the licence text is the authoritative version):
- Permitted — personal use, research, hobby projects, and use by charities, educational institutions, public research bodies, public-safety / health / environmental organisations, and government institutions. Read, modify, fork, and redistribute the source freely for any of those purposes.
- Not permitted — commercial use. "Commercial" means use that has an anticipated commercial application, including a consultancy charging for setup hours, a SaaS reselling Augury, or internal use at a for-profit company.
For a commercial licence, get in touch with the maintainer.
The PolyForm Noncommercial Licence is a source-available licence, not an OSI-approved "open source" licence — the OSI definition requires permitting commercial use. The source code is fully available under the terms above.