This release is a pre-release and may not be stable for production use.
Actaeon
An open-source AI threat hunter and alert triage analyst. Give it a hypothesis ("an Office app started encoded PowerShell this week") and Actaeon plans the hunt, queries your own data sources, follows pivots, and writes a verdict that cites its evidence and maps to MITRE ATT&CK. Point your alerts at it and it groups them into cases, investigates each one the same way, and says whether it is a true positive, a false positive or expected activity, with the fix. When it cannot be sure, it hands the work to a person instead of guessing.
It does not replace your SIEM or EDR. It works on top of them, reading what they already collect.
- Read-only investigations. Hunts and alert investigations only search and read. Response actions (isolate, quarantine, disable, ...) are never offered to a model; the only writes are ones an admin explicitly allows, such as opening a ticket.
- Response only with a person's approval (optional, off by default). Containment actions you define are proposed on true positives and run only after an analyst approves the exact call, with undo and an audit trail. Destructive operations (delete, wipe, shut down) are never possible.
- Works with what you already run. Every data source is reached through the Model Context Protocol (MCP), so it is not tied to any product. It ships with bridges for search-index APIs, read-only SQL databases, STIX/TAXII 2.1 servers and REST/OpenAPI services, and works with any other MCP server.
- AI is optional. Alert triage runs fixed, read-only checks first (decode the command, look up intel,
read the host's events and inventory, count accounts tried) and turns them into evidence-backed signals.
With
soc.analysis: rulesthat is all it does: no model, no tokens, seconds per case. A small local model can then judge the collected evidence, and your own endpoint can take only the hard cases. Drift checks, intel sweeps and saved-hunt replays also run with no model. - Your choice of model. A cloud model or one on your own hardware; each role (planner, analyst, reporter) can use a different one.
- Fully open source. Apache-2.0. Every feature is in this repository. There is no paid edition, no licence key and no telemetry.
Beta, solo-maintained. It has been tested in one home lab and on public and synthetic benchmarks, but not yet in production. It runs on one machine with SQLite by default, with PostgreSQL and separate worker processes as options. Treat verdicts as leads to verify, expect rough edges, and please open an issue when something is wrong. Read known limitations before relying on it.
The offline demo: synthetic data and a scripted run, no model. It shows the workflow, not detection
quality. Rebuild it with scripts/make_demo_gif.py.
| Investigation graph | Entities across hunts |
|---|---|
| Leads | ATT&CK coverage |
Alert triage: alerts grouped into cases, each with an AI verdict that a person reviews.
| A case: what happened, the evidence, the fix | Response actions (approve, reject, undo) |
|---|---|
| Entity graph of a case | Triage dashboard |
Try it in a minute
pipx install actaeon # or: pip install actaeon
actaeon demo --offline --run # synthetic data, scripted run (no AI, no keys)
ACTAEON_HOME=~/.actaeon-demo actaeon serve # open http://127.0.0.1:8611
From a checkout instead:
git clone https://github.com/ares-369/actaeon.git && cd actaeon
python -m venv .venv && . .venv/bin/activate && pip install -e .
actaeon demo --offline --run # synthetic data, scripted run (no AI, no keys)
ACTAEON_HOME=~/.actaeon-demo actaeon serve # open http://127.0.0.1:8611
Or with Docker, no Python needed (nothing is kept when it stops):
git clone https://github.com/ares-369/actaeon.git && cd actaeon
docker compose --profile demo up demo # open http://127.0.0.1:8611
The demo has a planted attack and a harmless look-alike, and all of its data is labelled SAMPLE.
--run also sends five sample alerts through alert triage (a document lure, password spraying, an admin
script, an ordinary failed sign-in, and an alert whose text tries to talk the AI into closing it), and a
pretend response connector lets you approve an action safely. See docs/demo.md.
Screenshots are from this demo; scripts/make_screenshots.py rebuilds them.
How a hunt works
- Plan. The planner model turns the hypothesis into steps, and asks for data by role (log search, endpoint, identity, email, asset, network, cloud, intel). It never asks for a product.
- Query. The analyst model calls connector tools. Before each call a validator requires a time range (when the tool takes one), caps result sizes, checks field names where the source lists them, and refuses write and code patterns. Calls are paced and time-limited.
- Pivot. The model follows what it finds to the same host, user or destination, in other sources and in intel. When a threat rests on thin evidence, it is asked to corroborate it first.
- Verdict. The outcome is one of
threat,no_results,telemetry_found_benign,logs_missingorinconclusive. Claims that do not cite a successful result are dropped, and claims whose values do not appear in the cited evidence lower the confidence. Missing data is reported as missing, never as clean. - Second look. A threat verdict gets a separate pass that tries to prove it wrong; if that pass cannot confirm it, the confidence is capped and the hunt goes to a person.
- Hand-off. When it cannot answer, a "needs analyst" lead opens. The lead says what was searched, what was missing and what to check next.
flowchart TD
H["Hypothesis<br/>(analyst, hunt pack, advisory, autopilot)"] --> P["Planner model<br/>asks for data by role"]
P --> A["Analyst model<br/>chooses the next tool call"]
A --> V["Query validator<br/>time range, result caps, field names, no writes"]
V --> G["Connector policy<br/>read-only tools, per-person access, pacing, time limit"]
G --> C["MCP connectors and bridges<br/>your SIEM, EDR, identity, intel, ..."]
C --> W["Untrusted-data wrapper<br/>random markers, prompt-injection scan"]
W --> A
G -. every call .-> L[("Hash-chained audit log")]
A --> X["Verdict checks<br/>cited evidence, values present, missing data = missing"]
X --> S["Second look on threats"]
S --> O["Verdict, lead or hand-off,<br/>Sigma draft, outputs"]
What is included
| Area | What you get |
|---|---|
| Hunting | Hypothesis hunts, saved hunts with scheduled replays, advisory-driven hunts, threat-actor and campaign hunts, an intel sweep over the indicator ledger |
| Entities across hunts | Every host, user, IP, domain and hash that findings relied on, with its history; entities that keep turning up in unresolved hunts are flagged as recurring (entities) |
| Inventory drift | What is new on each host since the last snapshot (listening ports, accounts, services, processes), with no model; new items open a lead (drift) |
| Hunt library | 65 ATT&CK-mapped hypotheses as one YAML file per hunt, a validator, and your own private packs alongside (hunt packs) |
| Sources | Any MCP server, plus built-in bridges for search indices, read-only SQL, STIX/TAXII 2.1 and REST/OpenAPI services. Each connector can carry query notes and examples in its own query language. actaeon connectors check tests a connector, and a one-file template helps you write your own |
| Intel | A local indicator and advisory store with first/last-seen tracking. Paste IOCs, import files, PDFs or URLs, or pull feeds. Export as STIX 2.1, or push a hunt's indicators to a TAXII 2.1 collection |
| Analyst work | Leads with assignment, status, resolution and history; chat on a finished hunt; feedback on findings; a timeline and an investigation graph (user, host, process, destination, intel match, each link tied to its evidence); an offline decoder for obfuscated command lines (base64, -EncodedCommand, gzip, hex, char codes, concatenation) that never runs them (actaeon decode, also a tool hunts can use) |
| Detection | Draft rules from a hunt (Sigma, plus the native queries that found data), optionally converted to each connector's query language with pySigma, and a backtest of how often they would have fired |
| Outputs | Email, webhook, or a write tool you explicitly allow (such as opening a case). A reply in the ticket can continue the hunt |
| Reports | Markdown, CSV and JSON; PDF and Word with the reports extra; an ATT&CK coverage view |
| Access | basic, local, OIDC single sign-on or a trusted proxy; viewer, operator and admin roles, mapped from your identity provider's groups; per-source limits so only some people can query (and see hunts over) sensitive sources (access). All of it is free |
| Interfaces | Web UI, CLI, REST API, and Actaeon itself as an MCP server |
| Hunting depth and upkeep | Quick / standard / deep profiles (calls, token cap, second look), hunts that resume after a restart, and retention of old hunts |
| Running it | pip, Docker / compose (non-root, read-only filesystem) or systemd. Runs with no internet access, with local models (air-gapped) |
Safety model
Actaeon reads attacker-controlled text (command lines, user agents, emails), so the controls are in code, not only in prompts:
- Read-only investigations. Write-like tools are blocked for hunts and alert investigations. Response and destructive actions are always blocked on that path, whatever the configuration says.
- Approval-gated response. The only way a response action runs is
soc.response.actions: a configured action on a connector with theresponserole, proposed for a case, approved by a named person (two withtwo_person), bound to the case as it was reviewed (new alerts or a new verdict make the approval stale), audited. Destructive tools are refused at config load and at call time. Approvals are not offered over MCP. - Query guard. Queries need a time window when the tool takes one. Result sizes, time per query, tool calls and runtime per hunt are capped, and tokens per hunt can be. Each connector is rate-limited. Leading wildcards, which force the index to scan every value, are refused on log indices.
- Untrusted data. Every tool result is wrapped in random markers and treated as data. Text in the logs that matches known prompt-injection patterns becomes a high-severity lead of its own.
- Evidence checks. A claim that cites nothing real is dropped, and the verdict is downgraded.
- Memory only from people. Models and data sources cannot write memory. "Benign" notes expire (90 days by default), so one wrong call cannot hide activity for good.
- Audit. Every tool call, including blocked ones, goes to an append-only, hash-chained log.
actaeon audit verifychecks it. - Privacy. Personal data can be masked before a prompt reaches a cloud model.
Details: docs/threat-model.md, docs/connectors.md, docs/privacy.md.
Results so far
| Test | Result |
|---|---|
| Lab benchmark on a frozen week of real SIEM data (11 labelled cases) | gemini-3.8-flash: 10 to 11 / 11 over four runs, all 5 threats found, no false positives |
| Same lab cases, other models | gemini-3.1-pro-preview 9 / 11 (3 of 5 threats; its second look talked it out of 2, which went to an analyst), gemini-3.1-flash-lite 8 / 11 (2 of 5 threats); no false positives |
| ExCyTIn-Bench sample (80 public investigation questions) | mean reward 0.512, 40 / 80 fully correct |
| Field test: implant planted where no detection rule covered it | found from host inventory with no alert behind it |
| Tokens per hunt on the lab data (gemini-3.8-flash) | about 210k to 250k input, more than half served from the provider's cache; about 4k output; about 20 model calls |
The samples are small, the lab cases were written by someone who knew the answers, and only Gemini models
have been measured. Read them as "it checks and clears correctly", not as proof that it finds every attacker.
actaeon bench --model <provider/model> runs the built-in demo cases (or your own) with any model,
and benchmarks/ has the runners for the lab and ExCyTIn tests. Results from other models are
welcome. Details, failures included, are in
docs/benchmarks.md and docs/field-test-2026-11.md.
Install
From PyPI (3.10+)
pipx install actaeon # or: pip install actaeon ; add extras with 'actaeon[all]'
actaeon init # config.yaml, .env and data/ in ~/.actaeon (ACTAEON_HOME to change)
actaeon serve # http://127.0.0.1:8601
From a checkout
python -m venv .venv && . .venv/bin/activate
pip install -e '.[all]' # or just -e . ; extras add cloud SDKs, PDF/Word reports, Sigma
actaeon init # writes config.yaml and .env (SQLite; add --database postgres to choose PostgreSQL)
actaeon serve # http://127.0.0.1:8601
PostgreSQL and separate workers (optional)
pip install -e '.[postgres]'
actaeon init --database postgres --db-url 'postgresql://actaeon:PASSWORD@db-host:5432/actaeon'
actaeon serve # with jobs.mode: queue in config.yaml, the server only records jobs
actaeon worker # run one or more of these, on this or other machines
Docker
docker compose up -d # http://127.0.0.1:8601, data in ./actaeon-data
Linux service (systemd)
sudo bash scripts/install.sh all
Actaeon refuses to start on a network address without a login. See docs/deploy.md.
Set it up for your environment
- Models. Pick a provider for each role (
planner,analyst,reporter): Ollama, Anthropic, Gemini, OpenAI, Azure OpenAI or any OpenAI-compatible server. Runactaeon models testto check them. See docs/models.md. - Connectors. Add your sources as MCP connectors with roles. Use read-only service accounts.
Run
actaeon connectors testto check them. See docs/connectors.md and docs/bridges.md. - Environment profile. Describe what runs here, what matters most and what is normal, so hunts fit your estate. See docs/company-setup.md.
- Check.
actaeon doctor.
Keep your organisation's setup in a private configuration folder (actaeon init --company DIR),
not in this repository.
Documentation
| Topic | Doc |
|---|---|
| Hunting, limits, verdicts, chat | docs/hunting.md |
| Alert triage: intake, cases, verdicts, second look | docs/alert-triage.md |
| Response actions and approval | docs/response.md |
| Triage playbooks | docs/playbooks.md |
| Saved hunts, schedules, sweeps, memory | docs/library.md |
| Inventory drift | docs/drift.md |
| Entities across hunts | docs/entities.md |
| Hunt packs (writing and sharing hypotheses) | docs/hunt-packs.md |
| Connectors and bridges | docs/connectors.md, docs/bridges.md |
| Intel store and feeds | docs/intel.md |
| Autonomy: web intel and autopilot | docs/autonomy.md |
| Outputs and ticket replies | docs/outputs.md |
| Models and providers | docs/models.md |
| Running with a local model (set-up and measured results) | docs/local-models.md |
| Privacy masking | docs/privacy.md |
| Organisation setup, roles and access | docs/company-setup.md, docs/access.md |
| Deployment, air-gapped networks | docs/deploy.md, docs/air-gapped.md |
| Actaeon as an MCP server | docs/mcp-server.md |
| Benchmarks | docs/benchmarks.md |
| Threat model, limitations | docs/threat-model.md, docs/known-limitations.md |
What it is not (yet)
- Not a SIEM or a full SOAR. It sits beside them as an investigator. It runs only the containment actions you define, after approval, and none by default.
- Not clustered by default. It uses SQLite on one machine, with nothing else to install. PostgreSQL is an install-time option for several machines; it is new and has not run in production yet.
- Measured with a few models only. Three Gemini models and two small local models were scored; other providers have no measured results yet. Small local models were not good enough to hunt in testing (on a 4 GB GPU a 7B model found 0 and a 4B reasoning model 1 of the 4 planted threats in the demo cases; docs/local-models.md). For alert triage the fixed checks change that: on 9 labelled cases from the lab's real data, the checks alone (no model) and the checks with a 4B local model both found all 4 planted attacks with no false alarms; the model alone found none. The rules were tuned on those cases, so treat it as a first result (docs/benchmarks.md).
- Not proven in production yet.
Acknowledgements
Actaeon builds on open work by many people:
- MITRE ATT&CK® for the technique data bundled with Actaeon (used under MITRE's terms of use), and the Model Context Protocol, which every connector speaks.
- Sigma and pySigma for detection drafts and conversion, and OASIS STIX and TAXII 2.1 for sharing intel.
- ExCyTIn-Bench for the public investigation benchmark (its judge prompts are used as published), and Ollama with the open-weight models it serves for local testing.
- Material Design Icons (a bundled subset), and Flask, Waitress, Requests, PyYAML and python-dotenv.
- The alert-triage design took ideas from the documentation of other open-source AI SOC projects. From AiSOC: an approver who is not the requester, approvals that expire, stating the evidence that argues against a verdict, sealed evidence exports, keeping secrets out of prompts, and measuring each model per task. From Vigil and Cerebro: separate triage and investigation roles, and a graph of the entities around each alert. No code was copied from them.
Thank you to everyone who builds and maintains them.
Contributing
Bug reports, hunt hypotheses (hunt packs), connectors and benchmark runs with other models are all welcome. See CONTRIBUTING.md and SECURITY.md for how to report a vulnerability.
pip install -e '.[dev]'
ruff check actaeon tests benchmarks scripts && node --check actaeon/static/app.js && pytest -q
License
Apache-2.0. See LICENSE, NOTICE, DISCLAIMER.md and CODE_OF_CONDUCT.md. All features are in this repository, under this licence.
Metadata
Release files for actaeon 0.4.0b0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| actaeon-0.4.0b0.tar.gz | 493.2 kB | With provenance | Details for actaeon-0.4.0b0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| actaeon-0.4.0b0-py3-none-any.whl | Python 3 | none | any | Details for actaeon-0.4.0b0-py3-none-any.whl |
Total release size: 961.0 kB
Release files / actaeon-0.4.0b0.tar.gz
| Download URL | actaeon-0.4.0b0.tar.gz |
|---|---|
| Size | 493.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9665eac79b7861faeefee339510282a79e5f6092d2a12134249736d4a7c211bb
|
|
BLAKE2b-256 checksum How to use checksums |
2060aad38ae30993260ed555f5e1158bf11893f9759c19e88bd509d41d642570
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logRelease files / actaeon-0.4.0b0-py3-none-any.whl
| Download URL | actaeon-0.4.0b0-py3-none-any.whl |
|---|---|
| Size | 467.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6b17d9516fa22e5a92170c7f26e3987dd10e58c8ca68ecc88aba8ffde4edf9ed
|
|
BLAKE2b-256 checksum How to use checksums |
9de8629fe0bd8eb8b3f15c19d4308a682f4cef1bef7371e00805222df1f577e0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logSecurity for actaeon 0.4.0b0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for actaeon-0.4.0b0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.