Public documentation for governed AI labor
SDKs/Governance/Connectors
Arx / Docs / Project Instructions

Documentation

Project Instructions

arxsec-app / CLAUDE.md

arxsec-app repo-root CLAUDE.md

Repository Layout

The repo has 31 top-level directories. The eight a code session needs to know about:

  • repo root — the main FastAPI API + Next.js dashboard.

Most application code lives here.

  • app/ — FastAPI app (routers under app/api/v1/,

runtime under app/runtime/, connectors under app/connectors/)

  • frontend/ — Next.js dashboard (App Router; route

groups under src/app/(dashboard)/)

  • supabase/migrations/ — Postgres migrations
  • tests/ — Python tests
  • atlas/ — the per-customer LLM workforce reasoner pod

(separate FastAPI service from this app repo's main API). Capabilities at atlas/app/capabilities/{architect,audit,brief,coach,decide,probe}.py; vector store at atlas/app/memory.py. Deployed via the Helm chart in atlas/charts/.

  • reference-agents/ — reference agent implementations

(workforce-transformation-analyst, atlas-ceo-aide, ~40 senior-IC patterns, ~40 senior-manager patterns). Each agent has its own manifests/job_description.yaml declaring function/level/shape/ declared_systems.

  • library/ — declarative bundles consumed at runtime:

policies, prompts, workflows. The oss-redteam-baseline policy bundle and canonical analyst prompt live here.

  • tools/ — operator-facing CLIs (e.g. tools/arxctl/ for

the 72-hour deploy).

  • load-tests/ — k6 scenarios + perf documentation.
  • docs/ — engineer + customer docs. Atlas spec at

docs/atlas/atlas-spec.md; deployment runbook at docs/deployment/72-hour-runbook.md.

  • tests/ — top-level integration tests (most unit tests live

under tests/).

When searching for "atlas," "workforce reasoner," or anything LLM- agent-orchestration-shaped, look in atlas/ first. When searching for routers, governance surfaces, or frontend, look in the repo root.

Git Workflow

After completing any feature branch work, always merge to main and push before finishing.

Steps:

  1. Complete work on the feature branch and push it
  2. git checkout main && git pull origin main
  3. git merge <feature-branch>
  4. git push origin main

Community / Open-Source Connector Pattern

ARX wraps community / open-source security tools (NVIDIA garak, promptfoo, PyRIT, PurpleLlama, agentic-radar, etc.) as first-class connectors so they inherit ARX's intercept → policy → audit → approval pipeline for free.

Three shared primitives keep this consistent:

  • app/connectors/_oss_runner.py — OSSToolRunner wraps

runtime/executor.py for CLI-in-Docker tools. Use OSSToolSpec to declare image (pin by digest in production), args, report path, sandbox profile, and timeout. Helpers parse_jsonl_stdout and parse_json_stdout cover the two common report shapes.

  • app/connectors/_findings.py — three normalized

Pydantic models that every OSS connector MUST return wrapped in a FindingsBundle: AIFinding (LLM red-team), PentestFinding (traditional pentest), AgentVuln (agent-security). Policies key off severity + attack_category uniformly across tools.

  • Connector tier metadata — CONNECTOR_METADATA in

app/connectors/__init__.py carries tier, license, homepage, maintenance_status, category. Community-tier connectors use the community-oss sandbox profile (runtime/sandbox.py) and the oss-redteam-baseline policy bundle (library/policies/).

To add a new OSS connector:

  1. Add a Dockerfile under docker/oss-tools/<tool>/ (non-root

arx user uid 10001, /work writable, pinned tool version, tool binary as ENTRYPOINT).

  1. Implement the connector module mirroring app/connectors/garak.py:

subclass BaseConnector, dispatch operations in _execute_impl, call OSSToolRunner.run, normalize results into FindingsBundle.

  1. Add to CONNECTOR_REGISTRY and CONNECTOR_METADATA in

app/connectors/__init__.py.

  1. Add a credential schema in app/connectors/schemas.py (use

LLM_PROVIDER_CREDS for AI-targeting tools; add the connector to _REQUIRES_ANY_LLM_PROVIDER_CRED so validation enforces "at least one provider key").

  1. Add tests under tests/test_oss_connectors.py (or a new

test_oss_<tool>.py once that file gets large).

  1. Optionally ship a workflow under library/workflows/<workflow>/

that uses the connector with the oss-redteam-baseline policy.