francescostabile/numasec

1. Repository shape

- This is a Bun-first TypeScript monorepo. The main product lives in packages/numasec, with supporting packages for a public SDK (packages/sdk), reusable shared utilities (packages/shared), and plugin authoring/runtime pieces (packages/plugin).

- Build/test/release is organized around Bun, Turbo, and GitHub Actions, with package-local workflows rather than a single root app.

2. Primary runtime: the terminal security agent

- packages/numasec is the actual product: a command-line security agent with a TUI, command palette, and session/operation management.

- The operator enters through CLI commands, then spends most of the time in the TUI under src/cli/cmd/tui, which renders home/session views, dialogs, sidebars, and operation lenses.

3. Core architectural idea: an “operation” as the source of truth

- The central domain object is the security operation. It carries target, scope, posture, agent choice, findings, evidence, replay artifacts, and report state.

- The README’s “operation memory” and “finding lifecycle” are reflected in src/core/operation, src/core/finding-adjacent tool surfaces, src/core/evidence, src/core/replay, src/core/plan, and session code under src/session.

4. Workflow engine: agents, runbooks, and tools

- src/agent, src/tool, and src/command define the user-facing security workflows.

- Runbooks are the structured workflows that keep the agent from making random tool calls; tools are the callable actions; agents are posture bundles such as AppSec, Pentest, OSINT, and hacking/security variants.

- This is the main control boundary: operator intent flows into an agent + runbook, which then chooses tools and writes back to the operation.

5. Model/provider boundary

- The project is model-agnostic through src/provider, with provider adapters and SDKs for multiple LLM ecosystems.

- The README explicitly names OpenAI, Anthropic, Google, xAI, Bedrock, OpenRouter, Ollama, Vercel AI Gateway, and OpenAI-compatible endpoints.

- Session prompting is provider-aware: src/session/prompt contains provider/model-specific prompt templates, and src/session/llm.ts ties prompts to model execution.

6. Execution layer: local shell, PTY, browser, HTTP, scanners

- Security work happens against the local machine and target environment through controlled execution surfaces: shell, PTY, browser automation, HTTP requests, scanners, and file operations.

- These are implemented across src/shell, src/pty, src/browser, src/scanner, src/file, src/git, and the generic effect/runtime layer under src/effect.

- The architecture assumes local tools are first-class and intentionally avoids replacing them.

7. Permission, opsec, and autonomy as a safety boundary

- src/permission, src/core/boundary, and tool-level schema/evaluation code define what the agent is allowed to do.

- The product positions this as “permissioned / auto execution,” meaning the system mediates tool calls rather than blindly executing every model request.

- This is an important diagram boundary: model reasoning sits behind policy and execution gating.

8. Persistence and evented state

- Durable state is stored in src/storage and the domain-specific SQL-backed modules such as src/session/session.sql.ts, src/project/project.sql.ts, src/sync/event.sql.ts, and migration history under packages/numasec/migration.

- State appears to be event- and record-oriented rather than just flat files: sessions, operations, projects, sync events, observations, and findings are persisted so work can resume and be replayed.

- The docs/NUMASEC_FILE_FORMAT.md and replay/share features suggest some derived artifacts are exported from this durable core.

9. Knowledge and research subsystem

- src/core/knowledge, src/tool/knowledge, src/tool/cve, src/core/methodology, and bundled methodology data (MITRE ATT&CK, PTES, WSTG) form the cyber knowledge layer.

- This subsystem enriches observed components and advisories with provenance-aware matching, applicability reasoning, and safe next actions.

- It is intentionally separated from finding creation: intelligence can inform the operator without becoming a reportable claim by itself.

10. Evidence, observation, finding, replay, report

- A major data flow is: tool output and observations → evidence store → findings → replay/report/share outputs.

- src/core/observation, src/core/evidence, src/core/replay, src/core/deliverable, and report/share/remediation tools encode this lifecycle.

- The architecture explicitly preserves weak signals, rejected claims, and proof semantics so report generation can be grounded in the actual operation history.

11. Server, SDK, and multi-client access

- src/server and src/mcp expose runtime capabilities through server-side interfaces, including HTTP API pieces, middleware, proxying, and MCP/OAuth support.

- packages/sdk contains generated client/server bindings for v1 and v2 APIs, so external tools or other apps can integrate with numasec programmatically.

- This separates the interactive terminal product from machine-to-machine access.

12. Plugin and extension model

- There is a dedicated plugin surface in src/plugin and a TUI plugin/runtime system in src/cli/cmd/tui/plugin.

- The repo also includes a separate packages/plugin package, indicating external extension support and reusable plugin primitives.

- Diagram-wise, this is a pluggable UI/action layer rather than part of the core security kernel.

13. Supporting packages and tooling

- packages/shared holds cross-cutting filesystem, hashing, retry, slug, and effect helpers shared across packages.

- Scripts under script/ and packages/numasec/script/ handle build, schema generation, migration checks, release, benchmarks, and packaging; Docker support exists for containerized use.

- This matters architecturally because it shows the repo is designed for distributable CLI/software, not just a library or web service.