argus - Argus. A minimal, educational EDR / endpoint monit

项目说明

Argus

A minimal, educational EDR / endpoint monitor written in Nim.

Argus observes what happens on a host — process, file and network events —
normalizes them into a single typed event model, and runs a declarative,
rule-based detection engine that raises alerts mapped to MITRE ATT&CK.

> ### ⚠️ Educational project — not a production EDR
>
> Argus exists to teach how endpoint detection works, not to protect a real
> fleet. It has no kernel driver, no tamper protection, no anti-e, no
> managed update channel, and no support commitment. A determined ad can
> tri avoid or disable it. Do not rely on it as a security control.
> Use it to read, to experiment, and to understand the pipeline that real EDRs
> implement at far greater depth.

Principles

Defensive and obser only. Argus reads telemetry. It never

injects into, tampers with, hides from, or modifies other processes. There is
no offensi in this codebase and none will be added.

Least pri, and honest about it. Each collector declares exactly

what it needs and what it can still see without it. argus doctor prints
that report before anything is collected. Argus never asks you to weaken host
security.

Normalize early. Raw platform structures stop at the collector boundary.

E downstream — engine, rules, sinks — sees only the normalized
Event type.

Never lose anything silently. When the bus fills it drops events and

*counts* them; when correlation state hits its cap it evicts and *counts*
that; when a collector cannot start it is *named*. A monitor that looks
healthy while observing nothing is worse than one that admits a gap.

Handle data responsibly. Command lines and file paths routinely contain

personal data. The default watch list is short and explicit rather than
"e, filtered later".

Pipeline

Quick start

Requires Nim 2.0+.

Or run the guided walkthrough, which is safe and self-contained:

Replaying a trace

The fastest way to see the whole thing work — and the way the rules are tested.
No host activity is observed; the trace is a file in the repository.

The last one is the point of the whole project: neither half is damning alone,
but the *sequence*, from the *same process*, inside a *time window*, is.

The same trace contains three benign apt writes to /etc. Nothing fires on
them — a test asserts that, because noise is how a real deployment gets muted.

What it can see

| Collector | Source | Pri | Limitation |
|-----------|--------|-----------|------------|
| Process | /proc polling | read /proc | misses processes shorter-lived than the interval |
| File | inotify (Linux) or directory polling | read the watched paths | inotify watches are not recursi misses churn between scans |
| Network | /proc/net/* + /proc/*/fd | unpri for your own processes; root to attribute all pids | polling misses short-li |

argus doctor reports this for your actual host. On a machine with no /proc
— macOS, for instance — it says so plainly rather than collecting nothing
quietly:

Rules

Rules are YAML. See rules/ for the 22-rule starter pack and
docs/design.md for the full format.

Nineteen operators (equals, in, regex, glob, path_under,
basename_in, cidr, gt/lt, exists, …), all/any/not composition,
and correlation rules that join a sequence of steps on shared fields inside a
time window.

E checkable is checked at load time — unknown field paths,
unknown operators, regexes that do not compile, gt given two ,
duplicate ids. A detection that silently ne is worse than one that
refuses to load:

Configuration

Every setting has a defensible default, so argus run works with no config at
all. Copy argus.example.yaml to argus.yaml to
o; argus config shows what is actually in effect and where it came
from.

Using it as a library

Status

All se are complete. See docs/design.md for
the event schema, collector interface, rule format and design rationale.

| # | Milestone | Status |
|---|-----------|--------|
| 1 | Scaffold, Event model, alert sinks | ✅ |
| 2 | Rule engine: YAML rules, field matching, ATT&CK | ✅ |
| 3 | Collector interface, event bus, process collector | ✅ |
| 4 | File collector (inotify + polling) | ✅ |
| 5 | Network collector with pid correlation | ✅ |
| 6 | Stateful correlation across a time window | ✅ |
| 7 | CLI, config, starter rule pack, demo | ✅ |

Deliberately not built

eBPF collection. Richer and cheaper than polling, and a much larger

project. The collector interface is designed so it could be added without the
engine noticing.

netlink proc connector. Would catch processes that polling misses, at the

cost of CAP_NET_ADMIN and a lot of struct marshalling.

A second platform. macOS EndpointSecurity and Windows ETW both fit behind

the existing collector interface.

Never

Process injection, tampering, hiding, e, or any capability whose purpose
is to act on another process rather than observe it. Argus reads. That is the
whole of its authority.

Testing

721 unit tests, no live host activity in any of them.

Parsers (/proc/<pid>/stat, /proc/net/tcp, inotify masks) are pure

functions tested against real-shaped input, including the cases that break
nai — a process legally named (evil) thing, IPv6
addresses stored as four little-endian words.

Collectors take their tree root as a parameter, so the exact production

code path runs against a fixture directory. No mocks.

Rules are tested by replaying recorded JSONL traces, which is deterministic

and provokes nothing on the machine running the suite.

License

MIT — see LICENSE.

项目信息

开发语言：Nim

Star 数：6

技术要点

该项目属于防护思路方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Argus. A minimal, educational EDR / endpoint monitor written in Nim. It collects process, file, and network telemetry, normalizes it, and runs a rule-based detection engine with MITRE ATT&CK mapping. Read-only and defensive by design.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。