Repository navigation
Releases
Actaeon v0.4.0-beta
Actaeon v0.4.0-beta: alert triage without a model
Alert triage no longer needs a model. Before any model sees a case, fixed read-only checks collect the
evidence the same way every time, and plain rules turn it into signals that cite it.
What is new
- Fixed evidence checks: decode the command line, look indicators up in intel, read the host's events
around the alert, read what runs, listens and which accounts exist on the host, count the accounts a source
tried and its successful sign-ins, and see which other hosts contacted the same destination. Field names are
found per connector, or set withfields:. - Signals such as an intel match, a download piped into a shell, a process running from a temporary path, a
hidden listening process, a second root account, or password spraying. A finding only counts for the alert
when it concerns the alert's own process, account, command, address or domain; other findings on the host
send the case to a person. soc.analysis: rules: triage with no model, no tokens, seconds per case. Rules never dismiss a case.- With a model, the model can add to what the checks proved but not take it away; a failed model falls back
to the rules. soc.escalate: send only the hard cases to a stronger model you choose, within a daily limit.
Measured
On 9 labelled cases over the lab's real data (4 planted attacks, 5 real non-threat alerts):
| Run | Correct | Attacks found | False alarms | Median per case |
|---|---|---|---|---|
| qwen3:4b alone | 5/9 | 0/4 | 0 | 555 s |
| fixed checks, no model | 9/9 | 4/4 | 0 | 9 s |
| qwen3:4b with the fixed checks | 9/9 | 4/4 | 0 | 692 s |
The rules were tuned on these cases, so this is a first, in-sample result. On three days of live lab alerts
(329 alerts, 10 cases, out of sample) the no-model rules raised no false alarm and closed nothing. Nine cases is
small; details and caveats in docs/benchmarks.md.
Status
Beta, solo-maintained, not yet run in production. Read docs/known-limitations.md.
Install: pipx install actaeon, then actaeon demo --offline --run.
Actaeon v0.3.0-beta
Actaeon v0.3.0-beta: alert triage
Actaeon now triages alerts as well as hunting. Alerts come in through a webhook, a polled connector or an
import. They are suppressed, de-duplicated and grouped into cases, and each case is investigated through
the same read-only MCP connectors, models and checks as a hunt. The work was started as a separate project
(Haymdhal) and merged here, so both share one codebase.
What is new
- Cases with a checked verdict. True positive, false positive, benign, needs analyst or logs missing,
with the story, the findings tied to evidence, the facts that point against the verdict and what could
not be established, ATT&CK techniques, and a fix (remediation steps or a tuning proposal). - A second look tries to prove a true positive wrong and a serious dismissal right. A high or critical
alert is never dismissed without an independent confirmation: it waits for a person. - Graphs on every case: entity graph, timeline and ATT&CK chain; a triage dashboard with verdicts per
day, AI and analyst agreement, noisiest rules and tokens per day. - Approval-gated response actions, off by default. Actions you define (isolate, disable, block) are
proposed on true positives and run only after a person approves the exact call; never by whoever
proposed it, never after the case changed, never after the proposal expired. Undo is labelled
reversible or compensating. Destructive operations are never possible, and hunts still never see
response tools. - Sealed evidence bundle per case (alerts, every call and result with digests, verdict, decisions,
digests of every prompt and reply, audit rows). - Secret-shaped values are removed from every prompt for every provider, hunts included.
actaeon triage-benchon the demo cases or your own labelled alerts, with a per-model table.
Measured
On 9 labelled cases over real lab data, a 4B local model (qwen3:4b on a 4 GB GPU) found none of the 4
planted attacks and called them false positives. None was closed: the guards sent all four to an analyst
(0 wrong closures, 0 false alarms). Small local models cannot triage; larger models have not been measured
on alert triage yet. Details in docs/benchmarks.md.
Status
Beta, solo-maintained, not yet run in production. Read docs/known-limitations.md.
Install: pipx install actaeon (or pip install actaeon), then actaeon demo --offline --run.
Actaeon v0.2.1-beta
Actaeon 0.2.1-beta: local reasoning models on Ollama work (a fix for qwen3-style thinking), and qwen3:4b is measured on a 4 GB laptop GPU. Install with pipx install actaeon (PyPI shows 0.2.1b0).
On the 8 built-in demo cases qwen3:4b got 4 right and found 1 of the 4 planted threats, with no false alarms; qwen2.5-coder:7b on the same GPU found none. Small local models are not good enough to hunt with yet; see docs/local-models.md.
Added
- qwen3:4b measured on a 4 GB laptop GPU (
docs/local-models.md,docs/benchmarks.md): 4 of 8 demo cases
correct, 1 of the 4 planted threats found, no false alarms; 4 to 13 minutes per hunt with thinking on.
Fixed
- Reasoning models on Ollama (such as qwen3): their thinking counts against the reply limit, so a 900-token
limit could be spent entirely on thinking and return an empty answer. The provider now leaves extra room
(think_tokens, default 6000; a cap, so other models are not slowed) and reports an answer-less reply
as an error. With this Ollama version,think: falsemade qwen3 write its reasoning into the answer
instead of skipping it, so leavethinkunset for it.
Actaeon v0.2.0-beta
Actaeon 0.2.0-beta adds inventory drift, entity tracking across hunts, an investigation graph, hunt profiles, resuming after a restart and data retention, plus access fixes for scheduled work. It is the first release on PyPI: pipx install actaeon (PyPI shows the version as 0.2.0b0).
Still a beta: tested in one home lab, on public and synthetic benchmarks, and in CI (the whole test suite on SQLite and on PostgreSQL), not yet in production. A local 7B model on a 4 GB GPU did not find the planted threats in the demo cases; see docs/local-models.md.
Security
- Two more checks on the verdict, so a confused model cannot quietly close a real finding: a
no_results
whose own findings cite searches that matched becomesinconclusiveand goes to an analyst, and a
benignverdict when an intel lookup matched is capped at confidence 50 and goes to an analyst. Both
were seen with a local 7B model on the demo cases. - Scheduled replays run as the person who saved the hunt; the scheduler's own work can be given an identity
(scheduler.groups); notes and saved hunts made from restricted hunts are restricted; the audit log names
the identity a call ran as. - The prompt-injection scanner also checks a normalised copy of each result (look-alike letters, words
split by-,_,.), payloads the offline decoder unpacks, and a few other languages, with broader
phrasings. Measured on new scored sets inbenchmarks/injection/: 24/24 on the set it was tuned on,
9/10 on a held-out set scored once, 0 false alarms on both and on 9,459 real lab alerts.
Added
docs/local-models.md: running with a local model, and what qwen2.5-coder:7b on a 4 GB laptop GPU did on
the demo cases (3 of 8 correct over two runs, none of the 4 planted threats found, no false alarms).- Ollama provider settings
num_ctx,timeout_secandthink(turns off a reasoning model's thinking
step). - Inventory drift: what is new on each host since the last snapshot (ports, accounts, services,
processes), with no model; new items and new hosts open a lead (docs/drift.md). - Entities across hunts: hosts, users, IPs, domains and hashes that findings relied on, with their history
and a "recurring" flag for entities in several recent unresolved hunts (docs/entities.md). - Investigation graph on each hunt: user, host, process, destination and intel match, linked to evidence.
- Hunt profiles (quick, standard, deep), hunts that resume after a restart, and retention of old hunts.
- PostgreSQL:
actaeon db migratecopies a SQLite data folder; the scheduler lock is held in the database. - Search-index bridge:
--leading-wildcard-hoursallows leading wildcards over short windows, so converted
Sigmacontainsrules can be backtested (counted day by day). - Three Gemini models on the lab benchmark, and the token usage per hunt, in docs/benchmarks.md.
gemini-3.8-flash 10 to 11 of 11 over four runs, gemini-3.1-pro-preview 9 of 11, gemini-3.1-flash-lite
8 of 11; no false positives. Gemini 4 Hydrogen and Argon did not work (known limitations). benchmarks/excytin/analyze.pysorts every missed question by cause from its stored tool calls. On the
recorded 80-question run: 18 ran out of tool calls (11 of them had already seen the answer), 8 were
model service errors, 6 malformed tool calls, 5 never reached the evidence, 3 saw it and answered
wrong. The runner now retries questions that die on a service error.- A second held-out prompt-injection set (multi-step, encoded, multilingual, email-borne), scored once:
11 of 16 attacks caught, 0 of 12 benign look-alikes flagged. Misses (non-English, non-Spanish text
and authority-style wording) are listed in docs/hunting.md and left unfixed in the score.
Changed
- README screenshots rebuilt from the current demo, shown under the demo GIF: a finished hunt, the
investigation graph, entities, leads and ATT&CK coverage. - Version format matches the author's other tools:
0.2.0-betain the code and tags,0.2.0b0on PyPI.
docs/project-standard.mdlists the shared naming, packaging and release rules. Install with
pipx install actaeon; publishing a GitHub release uploads to PyPI (trusted publishing). - The changelog follows Keep a Changelog;
SECURITY.mdhas the same layout as the other tools. - The icon font ships only the 100 icons the UI uses (7 KB instead of about 3.6 MB of font files), so the
wheel drops from 2.5 MB to about 0.36 MB. CI checks the five required packages and the wheel size, and
the wheel smoke test runs the offline demo. - When every search in a hunt matched nothing and the model answers
no_results, it is asked once to
search again more broadly first (small models tend to stack guessed filters into one query and stop). actaeon hunt --plan-only(alsoPOST /api/hunts/planand a Plan only button): the planning step
alone, with no data queried and no hunt stored.- Token usage records the part of the input served from the provider's prompt cache (Gemini, Claude,
OpenAI-compatible) next to input and output; hunt pages, reports andactaeon benchshow it. - Fewer tokens per hunt: older tool results are shortened in batches so the prompt start stays the same
(and can be cached), the analyst is told to stop once the evidence answers the hypothesis and sees the
calls used on each result, and tool results default to 8,000 bytes. On the lab benchmark with
gemini-3.8-flash: about 210k to 250k input tokens per hunt, down from about 440k, with the same score. - Gemini: optional
thinking_budget/thinking_level. - Usage is reported in tokens only (the optional
llm.pricessetting was removed). docker compose --profile demo up demo: the synthetic demo in a container, in memory, on port 8611.- README: CI, licence and Python badges, a diagram of a hunt, a plainer opening, the bridge types and the
offline decoder named, PostgreSQL and worker install lines.
Fixed
- Bridges accept relative times rounded down (
now-7d/d,now/h), as search indexes do; they were
refused before. - The investigation graph was wider than its box at laptop widths and cut off the Intel column; it now
shrinks to fit (and scrolls on small screens). The top bar no longer wraps to two lines at 1280 px
now that it has an Entities tab (labels hide below 1240 px, icons stay). - The demo data source read a range such as
@timestamp:[now-7d TO now]as three loose words and
matched nothing; it now supports ranges, as real search indexes do. Found by a local 7B model that
writes its time window into the query. - Local models: Ollama was called with its own default context window (2,048 to 4,096 tokens), which
silently drops the start of a longer prompt. Actaeon now asks fornum_ctxtokens (default 8192,
llm.providers.ollama.num_ctx) and reports a prompt that still fills the window as an error instead of
using the answer. The request timeout is configurable (timeout_sec, default 300). - Chat and the second look on threats failed silently on newer Gemini models (every reply a malformed
tool call), so threats were never confirmed. Every tool loop now declares its final action as a native
tool next tocall_tool, and requests without tools say so. With gemini-3.8-flash the second look now
confirms threats (confidence 80 to 95 instead of a cap of 60). - A malformed tool call that repeats after the retry is treated as an unusable reply (asked again), not
as an error that ends the hunt. - Parallel workers upgrading the same database could crash on "duplicate column"; column migrations are
now safe to run at the same time. actaeon bench: one case raising an exception no longer ends the whole run.- Gemini: the civic-integrity and jailbreak filters are relaxed along with the others.
Actaeon 0.1.0b2 (second beta)
Actaeon 0.1.0b2 is the second beta of an open-source, read-only AI threat hunter that works through MCP connectors and the model provider of your choice. Apache-2.0, every feature in this repository, no telemetry.
Still a beta: tested in one home lab, on public and synthetic benchmarks, and in CI (the whole test suite on SQLite and on PostgreSQL 16), not yet in production. Read docs/known-limitations.md before relying on it.
Install (Python 3.10+): download the wheel below and pip install actaeon-0.1.0b2-py3-none-any.whl, or clone the repository and pip install -e .. Then actaeon demo --offline --run for a scripted demo on synthetic data. Not published to PyPI.
Upgrading from 0.1.0b1: the Excel output was removed. A config with type: excel stops with a message; use the email output or the CSV/JSON/PDF/Word downloads instead.
Safety and cost
hunt.max_tokens: a token budget per hunt; when it is used up the model must give its verdict.hunt.max_query_sec(default 120): one tool call, retries included, cannot run longer, nor past
the hunt's own time limit.- The search-index bridge also refuses leading wildcards inside raw query clauses (wildcard,
regexp, query_string) on time-series indices. - Tool results that match known prompt-injection patterns ("ignore previous instructions", "mark
this host as benign", chat-template tags, fake verdicts) are flagged: the hunt goes to an analyst
as a high-severity "prompt injection" lead. Pattern-based, so it catches blatant attempts only. - Memory notes can expire; notes made from a benign or false-positive call expire after
memory.benign_note_days(90 by default). The model sees who wrote each note and when. - The audit log is hash-chained;
actaeon audit verifyandGET /api/audit/verifyfind changed
or removed rows.
Access
- Roles from identity-provider groups (
auth.group_roles, OIDCgroups_claim, proxy
proxy_groups_header,require_group_role). - Per-connector
access(groups,role:,user:). People outside it cannot use the connector, and
hunts that read it are hidden from them everywhere (hunts, leads, reports, exports, memory,
assistant conversations, detection drafts) and are not sent to outputs unless an output opts in.
See docs/access.md.
Removed
- The Excel output and the
excelextra. Use the email output for alerts; every hunt can still be
downloaded as CSV, JSON, PDF or Word. A config that still hastype: excelstops with a message
saying so.
Running at scale
- Storage choice at install: SQLite stays the default (nothing to install); PostgreSQL is optional
(actaeon[postgres],actaeon init --database postgres, the installer asks). The stores share one
code path; PostgreSQL gets its own full-text search and audit-log triggers. CI runs the whole test
suite on PostgreSQL. jobs.mode: queueandactaeon worker: the web server records jobs as named tasks and worker
processes run them, as the person who started each one. Stop and pause work across processes,
stale jobs are marked interrupted, and a lock file keeps a single scheduler. With SQLite, workers
run on the same machine as the server; with PostgreSQL they can run elsewhere (tested in CI on one
machine, not yet across several).
Detection
- Sigma drafts are converted with pySigma (optional
actaeon[sigma]plus your platform's backend) into
each connector's query language, set per connector with asigma:block, and the converted query is
backtested.actaeon sigma backends|convert,/api/sigma/convert,/api/sigma/backends.
Fixes
- Search-index bridge: a query string with a leading wildcard on a log index now fails with a clear
error. The index answered 0 for it, which a hunt could read as "nothing there".
Open standards and community
- Hunt packs: the 65 starter hypotheses are now one YAML file per hunt under
actaeon/hunts/<tactic>/,
with a schema,actaeon library validate, andhunt.library_dirsfor private packs. - STIX 2.1 export of the intel store (
actaeon intel export,/api/intel/export.stix) and of a hunt
(indicators, techniques and a report; STIX button). Newtaxiioutput pushes a hunt's bundle to a
TAXII 2.1 collection. actaeon connectors check: a contract check for hunting connectors (read-only hints, time ranges,
result caps, descriptions, TLS, timeouts), and a one-file connector template that passes it.actaeon bench --model provider/modeland--role-model, with--markdownfor the per-model results
table in docs/benchmarks.md.- Air-gapped guide, and a test that runs the offline demo and the UI with outbound connections refused.
Workflow
- Ticket replies:
POST /api/tickets/replyturns an analyst's answer in a ticket into a question
for Actaeon, a follow-up hunt (/hunt ...) or a resume (/resume). Answers go back through
outputs that listreply. Optional bearer token scoped to that path (tickets.token_env).
Checksums (SHA-256)
6947a8f8d06a7d8ff8a442203c2663db3f9925d5d47a177bb01f4cf8eb3bd0a3 actaeon-0.1.0b2-py3-none-any.whl
efc6528a2ae9a137492ef8a47c3767b324edf9c7eea1b128ed92b5114f1d5a99 actaeon-0.1.0b2.tar.gz
Actaeon 0.1.0b1 (first beta)
Actaeon 0.1.0b1 is the first beta: an open-source, read-only AI threat hunter that works through MCP
connectors and any model provider.
The first version meant for others to try. It is read-only, it runs on one machine, and it has been
tested in one home lab and on public and synthetic benchmarks (see docs/benchmarks.md and
docs/field-test-2026-11.md). Expect rough edges; please report them.
Hunting
- Give a hypothesis; Actaeon plans the hunt, queries your sources, pivots on what it finds and
writes a verdict (threat, no results, benign activity found, logs missing, inconclusive) that
cites its evidence and maps to MITRE ATT&CK. - Checks on every verdict: claims must cite successful results, the values a claim names must
appear in that evidence, a threat needs corroboration and gets a second look, and missing data
is reported as missing, never as clean. - When it cannot answer (out of steps, data missing, threat not confirmed, only known-good things
found, an error), the hunt is handed to an analyst: a "needs analyst" lead with what was
searched, what was missing and what to check next. - Environment profile: platforms, products, key assets, what is not present and what is known good,
given to every hunt. - 65 starter hypotheses including baseline and rarity hunts, a hunt library with scheduled replays
that need no model, hunt memory and analyst notes, chat about a finished hunt, a timeline,
draft detection rules (native queries and a checked Sigma draft) and a backtest of how often
they would have fired. - ATT&CK: IDs are checked against the bundled release (20.1) and revoked IDs map to their
replacement; a coverage view shows breadth per tactic and the log sources behind gaps.
Data sources
- Every source is an MCP connector tagged with a role (log search, endpoint, identity, email, asset,
network, cloud, intel). Read-only by default; response and destructive actions (isolate,
quarantine, kill, delete, disable, revoke, block, ...) are always refused, whatever the config. - Connector auth: bearer, API key, OAuth client credentials, and interactive OAuth sign-in
(actaeon connectors login). Tested with the public MCP reference servers over stdio and HTTP. - Built-in bridges for sources without an MCP server: search indices (with a snapshot mode for host
inventory and compact results), SQL (SQLite, MySQL/MariaDB, PostgreSQL), STIX/TAXII 2.1,
REST/OpenAPI and the web.
Intel
- A local intel store: paste or import indicators and advisories (text, files, URL, PDF, HTML) with
defang-aware extraction; a ledger with first and last seen; intel sweeps that search your logs
for new or changed indicators and triage the matches. - Web intel from RSS/Atom feeds and pages. Each new advisory is checked for relevance to your
environment first; only relevant ones are hunted, and every decision is kept in the ledger. - Threat-actor profiles and campaign hunts.
Working with it
- Web UI (leads, hunts, ask, library, intel, coverage, reports, connectors, settings), with a
phone layout. Leads with acknowledge, assign, close and history; reports in PDF, Word and
Markdown; outputs to email, Excel, a webhook or an allowed tool. - Auth: none (loopback only), basic, local accounts, OIDC or a trusted reverse-proxy header, with
viewer, operator and admin roles. It will not listen on a network address without a login. - Models per role (planner, analyst, reporter): Ollama, Anthropic, Gemini (API key or Vertex AI),
OpenAI, Azure OpenAI, any OpenAI-compatible endpoint, or a signed-in model CLI; fallbacks,
retries on rate limits, native tool calling where supported, token and cost tracking per hunt.
Personal data is masked before prompts reach cloud models. - Actaeon as an MCP server for other agents (
actaeon mcp,POST /mcp). - Install with
scripts/install.sh(systemd), Docker, orpip install -e .;actaeon doctor
checks a setup;actaeon demoruns on synthetic data with no model needed.
Benchmarks
actaeon benchwith labelled cases, parallel workers and reruns of cases that fail on service
errors; an ExCyTIn-Bench runner (benchmarks/excytin/) and a lab benchmark on a frozen copy of
your own data (benchmarks/lab/).
Fixed during testing
- Two hunts sharing one connector process could lose each other's replies.
- Filtered field lists made the field guard refuse valid fields.
- The model's last-turn tool call or a malformed reply could end up as the answer.
- Per-hunt token counts showed the server's running total.
- Loopback and private addresses from news articles were stored as indicators.
- Short rate limits locked a model out for an hour.
- A count that matched an indicator did not count as evidence for it.
- Table cells in the UI broke words in the middle.
Known limitations
See docs/known-limitations.md. In short: one process with SQLite (no high availability), benchmark
numbers for one model only, and hunts flag your own administration until the known-good list
describes it.
Results so far
| Test | Result |
|---|---|
| Lab benchmark on a frozen week of real SIEM data (11 labelled cases) | 11 / 11; 5 of 5 threats found, 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 |
One model and small samples; details and failures in docs/benchmarks.md and docs/field-test-2026-11.md.
Install
git clone https://github.com/ares-369/actaeon && cd actaeon
sudo bash scripts/install.sh all # systemd service in /opt/actaeon
# or: docker compose up -d
# or: pip install -e '.[all]' && actaeon demo --offline --runNot on PyPI yet.