CyberAg Documentation

Architecture

CyberAg is a serverless, event-driven platform on AWS with a React console, Gemini evaluation pipeline, and tamper-evident audit storage.

High-level diagram


Customer Estate (agents, MCP, NHIs)
        │
        ├── sync ──► Connectors Lambda ──► DynamoDB
        │
        └── runtime ──► Guardrail Gateway ──► EventBridge
                              │
                              ▼
                    ┌─────────────────────┐
                    │   cyberag-events    │
                    └─────────┬───────────┘
          ┌───────────────────┼───────────────────┐
          ▼                   ▼                   ▼
     API Lambda          Eval Workers         Replay Engine
          │                   │                   │
          └───────────────────┴───────────────────┘
                              │
                    DynamoDB + S3 Audit Vault

Repository layout

Path	Role
`apps/console`	Operator dashboard (Vite + React)
`apps/marketing`	Public marketing site
`apps/docs`	Static documentation portal
`packages/ui`	Design system + Storybook
`packages/types`	Shared Zod schemas
`packages/sdk`	Typed HTTP client
`services/api`	REST API Lambda
`services/eval`	SQS-driven Gemini workers
`services/guardrail-gateway`	Low-latency runtime guardrail
`services/connectors`	Connector sync workers
`services/replay`	Decision replay engine
`infra/`	AWS CDK stacks

Data model (DynamoDB `cyberag-main`)

Single-table design with composite key pk / sk:

Entity	pk	sk
Agent	`AGENT#{id}`	`META`
Identity	`IDENTITY#{id}`	`META`
Connector	`CONNECTOR#{id}`	`META`
Policy	`POLICY#{id}`	`v{version}`
Violation	`VIOLATION#{id}`	`{iso-ts}`
Guardrail event	`GUARDRAIL#{id}`	`{iso-ts}`
Red team run	`REDTEAM#{id}`	`{iso-ts}`
Audit entry	`AUDIT#{id}`	`{iso-ts}`
Replay	`REPLAY#{decisionId}`	`{iso-ts}`
Kill switch	`KILLSWITCH`	`STATE`
Discovery graph	`DISCOVERY#GRAPH`	`META`

EventBridge (`cyberag-events`)

DetailType	Producer	Consumer
`EvalRequested`	API	Eval workers
`RedTeamRunRequested`	API	Eval workers
`AskRequested`	API	Eval workers
`HardeningRequested`	API	Eval workers
`ReplayRequested`	API	Replay engine
`ConnectorSyncRequested`	API / scheduler	Connectors
`GuardrailBlocked`	Guardrail	Audit / console feed

Local development stack

LocalStack emulates AWS on port **4566**. CDK deploys the same stacks via infra/bin/cyberag-local.ts.


Console (:3002) ──HTTP──► API Gateway (LocalStack)
                              │
                         Lambda functions
                              │
                    DynamoDB + S3 + EventBridge + SQS

Bootstrap: npm run start:local or step-by-step in LOCAL_SETUP.md.

Production vs local

Feature	Local	Production
Region	us-east-1 (LocalStack)	eu-west-1 workload
Auth	Bypassed	Cognito MFA
S3 retention	7 days	365 days COMPLIANCE
Encryption	AWS-managed	KMS CMK
Edge	N/A	CloudFront (us-east-1)

Eval models

**Gemini 2.5 Pro** — red team, policy lint, RAG, prompt hardening

**Gemini 2.5 Flash** — runtime guardrail classification

Results are signed (signedHash) and written to the Audit Vault.