vero-audit-guard

The Watchtower for the Vero Protocol. Automated security monitoring, formal static analysis, and an immutable on-chain audit trail — all in one place.

Architecture: Read the root architecture for component boundaries, data contracts, security invariants, Mermaid diagrams, and end-to-end flows.

---

Security-First Stance

vero-audit-guard treats every line of the Vero Protocol as a potential attack surface. Nothing ships without:

1. Static analysis — scanner-engine catches unsafe Rust patterns, unchecked storage writes, and incomplete code before they reach mainnet.
2. Real-time monitoring — anomaly-detector watches the relayer service 24/7 for nonce spikes, failed-transaction bursts, and unauthorized address interactions.
3. Policy compliance — audit-guard enforces Policy as Code on every PR using OPA, flagging non-compliant code before review.
4. Immutable audit history — verifiable-audit-trail hashes every audit report and anchors it to the Stellar ledger, making tampering detectable by anyone.
5. Zero-tolerance on CRITICAL — The CI pipeline hard-blocks any PR containing a CRITICAL static analysis finding or policy violations.

---

Automated Monitoring Topology

┌─────────────────────────────────────────────────────────────────┐
│                        VERO ORGANIZATION                        │
│                                                                 │
│  vero-core-contracts ──── scanner-engine ─────────┐            │
│       (Soroban/Rust)       (Rust binary)           │            │
│                                                    ▼            │
│  vero-relayer-service ── atomic-rpc-relayer-bridge ──────┐      │
│       (Node.js)             (TypeScript)                  │      │
│                                  │ metrics                │      │
│                                  ▼                        │      │
│                          anomaly-detector                 │      │
│                                                          ▼      │
│                         GitHub PRs ──── audit-guard ──────┐    │
│                         (Pull Requests) (OPA/Rego)       │      │
│                                                          ▼      │
│                                          verifiable-audit-trail │
│                                              (Stellar memo TX)  │
│                                                  │              │
│                                                  ▼              │
│                                          STELLAR LEDGER         │
│                                         (immutable hash store)  │
└─────────────────────────────────────────────────────────────────┘

Component Summary

Component	Language	Role
scanner-engine	Rust	Static and governance analysis of Soroban contracts
anomaly-detector	TypeScript	Observational relayer monitoring and alerts
atomic-rpc-relayer-bridge	TypeScript	Atomic RPC relaying with integrity verification
src/audit-guard	Rust + TypeScript	OPA policy evaluation and security analyzers
verifiable-audit-trail	TypeScript	Report hash verification and Stellar anchoring
BUILD_GUARD.sh	Bash	Local and CI orchestrator
.github/workflows/	YAML	PR-gated security pipeline

---

Directory Structure

vero-audit-guard/
├── src/audit-guard/         # OPA policy engine for PR compliance
│   ├── src/policy-engine.ts
│   ├── policies/pr_compliance.rego
│   └── package.json
├── scanner-engine/          # Rust static analyzer
│   ├── Dockerfile
│   └── src/main.rs
├── anomaly-detector/        # TypeScript relayer monitor
│   ├── Dockerfile
│   └── src/index.ts
├── atomic-rpc-relayer-bridge/  # Local RPC/metrics bridge
│   ├── Dockerfile
│   └── src/index.ts
├── verifiable-audit-trail/  # On-chain audit hash anchoring
│   ├── Dockerfile
│   └── src/index.ts
├── docker/sample-target/    # Clean fixture scanned by compose
├── reports/                 # Generated scan reports (gitignored content)
├── docker-compose.yml       # Local multi-service pipeline
├── ARCHITECTURE.md          # Root architecture, contracts, and invariants
├── .github/workflows/
│   ├── security-scan.yml    # PR-gated CI pipeline
│   ├── policy-compliance.yml # OPA policy compliance checks
│   └── anchor-on-merge.yml  # Anchors audit trail on merge to main
├── BUILD_GUARD.sh           # Local automation script
├── CONTRIBUTING.md          # Contributor + compose workflow
├── POLICY_AS_CODE.md        # Policy engine documentation
├── INCIDENT_RESPONSE.md     # Emergency runbook
├── VULNERABILITY_DISCLOSURE.md  # Bug bounty & reporting
├── SECURITY.md              # Security policy & reporting
├── CHANGELOG.md             # Release history
└── TODO.md                  # Pending work tracker

---

Incident Response Procedures (IRP)

See INCIDENT_RESPONSE.md for the full runbook.

Quick Reference:

Severity	Response SLA	First Action
P0 (CRITICAL)	15 min	Page on-call + invoke emergency_pause on contract
P1 (HIGH)	1 hour	Isolate relayer, rotate keys
P2 (MEDIUM)	4 hours	Investigate, patch, re-scan
P3 (LOW)	24 hours	Track in backlog, schedule patch

---

Getting Started

Read ARCHITECTURE.md for system boundaries, data contracts, integration flows, failure behavior, and security invariants before changing cross-package behavior.

Prerequisites

• Rust toolchain (rustup install stable)
• Node.js ≥ 20
• cargo, npm
• cargo-audit (cargo install cargo-audit --locked)
• Docker + Compose v2 (only required for the containerised pipeline)

Run the Full Guard Locally

chmod +x BUILD_GUARD.sh
./BUILD_GUARD.sh [path/to/vero-core-contracts]

This will:

1. Audit Rust dependencies with cargo audit so known vulnerable crates fail the guard.
2. Build and run the Rust static analyzer.
3. Run anomaly-detector tests.
4. Build the audit trail module.
5. Compute and optionally anchor report hashes on Stellar.
6. Report the security health status.

Docker Compose (local multi-service pipeline)

Docker Compose wires scanner-engine, atomic-rpc-relayer-bridge, anomaly-detector, and verifiable-audit-trail so you can exercise the full local pipeline without installing Rust/Node toolchains on the host.

Prerequisites: Docker Engine with Compose v2.

cp .env.example .env   # optional — defaults work for a dry-run
docker compose up --build

What comes up:

Service	Role in compose	Lifetime
scanner-engine	Static-analysis against ./docker/sample-target (override with SCAN_HOST_TARGET)	One-shot; writes reports/latest-scan.json
verifiable-audit-trail	SHA-256 of reports; Stellar anchor when AUDIT_KEYPAIR_SECRET is set	One-shot after the scanner succeeds
atomic-rpc-relayer-bridge	Local HTTP metrics server (GET /metrics, GET /health, GET /audit-log)	Long-running on port 8545; protected endpoints require AUTH_TOKEN
anomaly-detector	Polls the bridge metrics URL and emits anomaly alerts	Long-running

Useful commands:

# Follow logs for the long-running monitor
docker compose up anomaly-detector atomic-rpc-relayer-bridge

# Scan a local checkout of vero-core-contracts instead of the sample target
SCAN_HOST_TARGET=/path/to/vero-core-contracts docker compose up scanner-engine verifiable-audit-trail

# Tear down containers (bind-mounted ./reports is kept)
docker compose down

See CONTRIBUTING.md for the compose workflow, environment variables, and service ports.

See ARCHITECTURE.md for the container topology and integration contracts.

Environment Variables

Variable	Component	Description
AUDIT_KEYPAIR_SECRET	audit-trail	Stellar secret key for on-chain anchoring
SCAN_HOST_TARGET	scanner-engine	Host path mounted as the scan target (compose)
BRIDGE_PORT	rpc-relayer-bridge	Host port for the local metrics server (default 8545)
DISABLE_ATOMIC_VERIFICATION	rpc-relayer-bridge	Set to true to disable atomic verification (trades security/trust for latency/availability).
RELAYER_METRICS_URL	anomaly-detector	HTTP endpoint exposing relayer metrics JSON
AUTHORIZED_ADDRESSES	anomaly-detector	Comma-separated list of allowed relayer addresses
NONCE_SPIKE_THRESHOLD	anomaly-detector	Nonce delta threshold (default: 50)
FAILED_TX_THRESHOLD	anomaly-detector	Failed TX count threshold (default: 10)
STELLAR_NETWORK	audit-trail	mainnet or testnet (default: testnet)
HORIZON_URL	audit-trail	Horizon server URL
POLICY_BUNDLE_SIGNATURE	audit-guard	Detached hex signature over the signed policy-bundle manifest
POLICY_BUNDLE_SIGNERS	audit-guard	Comma-separated trusted policy-bundle signer public keys

Note on Atomic Verification (DISABLE_ATOMIC_VERIFICATION): By default, the atomic-rpc-relayer-bridge requires majority verification for replay-safe requests. POST, PUT, and DELETE are submitted once and are not cross-verified unless the caller explicitly declares idempotency or provides an idempotency key. Setting this flag to true disables cross-endpoint verification, which trades response integrity for lower latency and higher availability. The only accepted values are true and false; invalid values stop server initialization instead of silently changing the verification policy.

---

Security Contacts

• Bug reports: See VULNERABILITY_DISCLOSURE.md
• Emergency: security@vero.xyz
• PGP: https://vero.xyz/.well-known/security.txt