Prog-Prober/AGENTS.md

AGENTS.md

Working notes for coding agents in this repository. Read docs/architecture.md and CONTEXT.md before making design decisions.

What this is

Prog-Prober is a Linux-hosted, local-first desktop workbench for analyzing untrusted Windows PE (primarily) and ELF binaries. It is agent-first: the Tool API is the product surface, exposed to the UI, CLI, and MCP. The full specification is docs/architecture.md; the terminology is CONTEXT.md.

Non-negotiable invariants

Never weaken these; if a change appears to require it, stop and raise an ADR. See docs/architecture.md §3.

1. Samples are read-only and content-addressed (samples/<sha256>).
2. Nothing untrusted executes on the host.
3. Detonation happens only in a disposable sandbox.
4. Egress is default-deny; only the sinkhole proxy is reachable.
5. The sandbox shares no host network namespace.
6. Teardown is verified and an attestation is recorded per run.

Additionally:

• Never commit malware, samples, or derived case artifacts. cases/, samples/, and artifacts/ are gitignored.
• Do not add a dependency that is non-commercial (e.g. Cosmograph branded packages, CC-BY-NC). Prefer MIT/Apache-2.0. Record new dependencies in THIRD_PARTY.md.

Commands

Task	Command
Build Rust core	cargo build
Test Rust core	cargo test
Lint Rust	cargo clippy --all-targets -- -D warnings
Format Rust	cargo fmt
Install JS deps	pnpm install
Typecheck UI	pnpm typecheck
Build UI/apps	pnpm build
Python workers	python -m progprober_workers (from workers/python)

Toolchains present in the reference environment: Rust nightly, Node 22 + pnpm, Python 3.14, Podman (not Docker). Container work targets Podman.

Architecture rules

• Process topology: Electron main spawns the Rust progprober-core sidecar. The renderer talks to the core over a localhost WebSocket carrying JSON. Python workers are spawned by the core over stdio JSON-RPC. Do not load Rust as an Electron native addon.
• One API, three faces: implement Tool API operations once in the core; the UI, CLI, and MCP (rmcp) are thin adapters. Do not create a second backend.
• Type generation: TypeScript types for the control plane are generated from Rust (ts-rs). Do not hand-maintain DTOs.
• Everything is a job: tool calls are cancellable, progress-streamed, and cache-aware.
• Static engine is Ghidra via PyGhidra. Add Rizin/angr only as optional backends behind an interface.
• Storage: SQLite for case metadata/cache keys; LadybugDB for nodes, edges, vectors, and FTS; graphology in memory for the renderer. Do not add another database without an ADR.
• Renderer: @cosmos.gl/graph for GPU layout. The canonical graph is normalized; the renderer gets a flattened typed-array projection.

Conventions

• Rust: cargo fmt + cargo clippy clean; keep the core's failure domain independent of the UI.
• TypeScript: no any; prefer generated types.
• Python: stdio JSON-RPC framing must stay consistent with the core's protocol.
• Do not add code comments unless they explain non-obvious intent.
• ADRs live in docs/adr/ and follow the existing template; add one for every architectural decision.

Git

• Do not commit unless explicitly asked.
• Never commit secrets, samples, or case data.
• Keep commits scoped; the repo's main branch is the integration branch.

Phases

1. Static workspace and graph MVP, with the Tool API and MCP adapter from day one.
2. Dynamic sandbox and network sinkhole.
3. Emulation, defense probing, and crash telemetry.
4. RAG signature intelligence.

Work should trace to an issue in the tracker; keep changes within the current phase unless a dependency demands otherwise.