Repository navigation
Actaeon v0.2.0-beta
Pre-release
Pre-release
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.