Argos

Runtime Observability & Integrity Monitor for LangGraph Agents

Argos Panoptes — the hundred-eyed all-seeing watcher of Greek myth

---

LangGraph agents make decisions based on a shared state object. Every node reads from it. Every node writes to it. If that state is poisoned — through prompt injection, memory tampering, serialization exploits, or malicious tool outputs — every downstream decision the agent makes serves the attacker, not you.

Argos is an open-source runtime observability & integrity monitor purpose-built for LangGraph agent state. It wraps your agent, watches every state transition in real time across four detection layers, and halts execution before a compromised agent takes an irreversible action.

from argos import Argos

watcher = Argos(graph, rules="config/rules.yaml")
result = watcher.run(input_data)

Three lines. Full runtime protection.

---

🛑 The Threat Is Real

These are not theoretical attacks. All three are documented in 2024–2025 research:

• CVE-2025-64439 — Checkpoint Deserialization RCE
  LangGraph's default JsonPlusSerializer was vulnerable to remote code execution via malicious JSON payloads injected into checkpoint storage. The exploit triggers on read, not write — making it invisible to write-time scanners.
• Microsoft Email Agent Memory Poisoning (Greshake et al., 2024)
  A LangGraph email agent was compromised by injecting a poisoned memory string. The agent autonomously began forwarding all sensitive communications to an attacker-controlled address. 40% success rate. Zero human interaction required.
• MemoryGraft (arXiv, Dec 2024)
  Persistent attack technique that implants malicious "successful experiences" into an agent's long-term memory, exploiting the semantic imitation heuristic. Survives across sessions. Not detectable by structural diffing alone.

Argos defends against all three.

---

🏗️ Architecture

Argos patches every node in a compiled LangGraph graph with pre and post execution hooks. Before each node runs, the pre-hook captures a state snapshot and checks the halt signal. After each node runs, the post-hook captures the new state, computes a structural diff, and routes the transition through all four detection layers in parallel.

flowchart LR
    A[LangGraph Agent] -->|state| B[Argos Watcher]
    B --> C[Pre-Hook: Snapshot + HALT check]
    C --> D[Node Execution]
    D --> E[Post-Hook: Diff + Detection]
    E --> F1[Layer 1: Snapshot Diff]
    E --> F2[Layer 2: Semantic Anomaly]
    E --> F3[Layer 3: Rule Engine]
    E --> F4[Layer 4: Behavioral Monitor]
    F1 --> G[Alert Bus]
    F2 --> G
    F3 --> G
    F4 --> G
    G -->|HALT| H[Block Next Node]
    G -->|Audit| I[(SQLite HMAC-signed)]

Loading

Four Detection Layers

• Layer 1 — Snapshot & Diff Engine
  Computes structural diffs between consecutive state snapshots using deepdiff. Every snapshot is SHA-256 hashed and HMAC-SHA256 signed for tamper-evident audit integrity.
• Layer 2 — Semantic Anomaly Detector
  Uses sentence embeddings (all-MiniLM-L6-v2) to compute cosine similarity between consecutive state values. A baseline profiler learns per-field similarity distributions from clean runs and flags deviations beyond a statistical z-threshold. Catches MemoryGraft-style attacks where state is semantically poisoned without structural changes.
• Layer 3 — Rule Engine
  YARA-inspired integrity rules defined in YAML. Rules are validated with Pydantic v2 and matched using google-re2 (linear-time regex, ReDoS-immune). Ships with default rules for system prompt immutability, external URL detection, and token-limit enforcement.
• Layer 4 — Behavioral Monitor
  Tracks node execution patterns using networkx. Detects infinite loops, unauthorized state transitions in strict topology mode, timing anomalies, and tool call frequency spikes.

Three Alert Levels

Level	Behavior
WARNING	Log and continue
CRITICAL	Log, notify all handlers, continue with monitoring flag
HALT	Block all subsequent node execution. Require human approval to resume.

---

⚙️ Installation

# Requires Python 3.11+
git clone https://github.com/Vasco1290/Argos.git
cd Argos

python -m venv .venv
.venv\Scripts\activate    # Windows
source .venv/bin/activate # macOS / Linux

pip install -e ".[dev]"

---

🧪 Demo — See an Attack Being Caught

Run the included email agent memory poisoning demo:

python demo.py

The demo simulates the Greshake et al. 2024 attack scenario:

1. A LangGraph email agent processes incoming mail across three nodes: retrieve → summarise → send
2. Four baseline runs profile the agent's normal semantic state
3. Run 5 injects a poisoned email attempting to redirect forwarding to attacker@evil.com
4. Argos's Rules layer catches the forwarding address mutation (FWD-001)
5. Argos's Semantic layer independently catches the same attack with a z-score of ~1654
6. The send node never executes. No email is delivered to the attacker.

End-to-end in under 30 seconds.

---

🛠️ Usage

Basic Monitoring

from langgraph.graph import StateGraph
from argos import Argos

graph = StateGraph(MyState)
# ... define nodes and edges ...
compiled = graph.compile()

watcher = Argos(compiled, rules="config/rules.yaml")
result = watcher.run({"messages": [...]})

Custom Configuration

from argos import Argos, WatcherConfig

config = WatcherConfig(
    db_path="my_audit.db",
    webhook_url="https://hooks.example.com/alert",
    enable_semantic=True,
    enable_rules=True,
    enable_behavioural=True,
    enable_canary=True,
)

watcher = Argos(compiled, config=config)

Handling HALT

from argos.core.alerts import ArgosHaltException

try:
    result = watcher.run(input_data)
except ArgosHaltException as e:
    print(f"Attack blocked: {e.alert.explanation}")
    # ... investigate, then approve resumption ...
    watcher.resume()
    result = watcher.run(input_data)

Writing Rules

config/rules.yaml:

rules:
  - id: FWD-001
    field: forward_to
    operator: EQUALS
    value: "user@company.com"
    level: 60  # HALT
    description: "Email forwarding address must always be the verified user address."

  - id: PROMPT-001
    field: system_prompt
    operator: REGEX
    value: "^You are a helpful assistant"
    level: 50  # CRITICAL
    description: "System prompt must not be modified at runtime."

---

🧪 Testing

pytest argos/tests/ -v

109 tests, 0 failures, ~11 seconds.

Coverage includes:

• Cryptographic integrity verification (HMAC tampering detection)
• Simulated prompt injection scenarios
• Memory poisoning attack simulation
• Canary field exfiltration detection
• Behavioral loop detection
• Multi-session isolation

---

📂 Project Layout

argos/
├── core/
│   ├── alerts.py      # AlertEmitter, three-level severity, HALT mechanism
│   ├── snapshot.py    # State capture + HMAC-signed audit trail
│   ├── watcher.py     # Main wrapper, node patching, layer orchestration
│   ├── rules.py       # YARA-inspired YAML rule engine
│   ├── semantic.py    # Embedding-based anomaly detection
│   └── behaviour.py   # Execution pattern monitoring
├── canary/
│   └── canary.py      # Sentinel field injection + exfiltration detection
├── dashboard/
│   └── terminal.py    # Real-time Rich terminal UI
├── api/
│   └── server.py      # Optional FastAPI monitoring REST API
└── tests/             # 109 tests across all modules

---

🗺️ Roadmap

• Core detection layers (alerts, snapshot, watcher, rules, semantic, behavioural, canary)
• Cryptographic audit trail with HMAC-SHA256 tamper detection
• Working email agent memory poisoning demo
• 109 passing tests on Python 3.11
• Community attack signature library
• Multi-framework support (CrewAI, AutoGen, LlamaIndex)
• LLM-powered alert triage and incident summary
• Cross-agent provenance tracking in multi-agent systems
• Differential privacy enhancements for federated audit sharing
• Formal verification layer for high-stakes deployments

---

🤝 Contributing

Issues and pull requests are welcome. Argos is intended to grow into the de facto open-source security standard for agentic AI systems. The attack signature library especially benefits from community contributions — if you discover a novel attack pattern, please open an issue.

---

📄 License

Apache License 2.0 — see LICENSE.

The Apache 2.0 license includes an explicit patent grant clause, providing patent protection for adopters. This is important for security tooling intended for enterprise deployment.

---

📝 Citation

If you use Argos in academic work:

@software{rawal2026argos,
  author = {Rawal, Harshit},
  title = {Argos: open-source runtime observability & integrity monitor for LangGraph Agents},
  year = {2026},
  url = {https://github.com/Vasco1290/Argos},
}

---

👤 Author

Harshit Rawal
GitHub: @Vasco1290
LinkedIn: Harshit Rawal

Built to explore reliability, integrity, and observability patterns for production LangGraph deployments.