Universal Adversarial Mesh (UAM)

A scalable, multi-agent orchestration framework that operates as a continuous, autonomous Red/Blue team. UAM is target-agnostic – it can audit, exploit, and remediate vulnerabilities across infrastructure, applications, and platforms through a pluggable module architecture.

╔═══════════════════════════════════════════════════════════╗
║            Universal Adversarial Mesh (UAM)               ║
║     Autonomous Red/Blue Team Orchestration Framework      ║
╚═══════════════════════════════════════════════════════════╝

How It Works

UAM runs a complete adversarial loop in nine stages:

 Recon     Chain      Exploit    Post-     Multi-     Detect    Evaluate  Remediate   Validate
                                Exploit    Stage
┌──────┐  ┌──────┐   ┌──────┐  ┌───────┐  ┌──────┐   ┌──────┐   ┌──────┐  ┌──────┐   ┌───────┐
│Scan  │─▶│Decide│──▶│Attack│─▶│Pivot  │─▶│Chain │──▶│Sense │──▶│Score │─▶│Patch │──▶│Re-run │
│Target│  │Order │   │Target│  │Persist│  │Follow│   │Threat│   │Result│  │Target│   │Exploit│
└──────┘  └──────┘   └──────┘  │Exfil  │  │  Up  │   └──────┘   └──────┘  └──────┘   └───────┘
  Red      Chain      Red      └───────┘  └──────┘    Blue       Judge      Blue       Closed
  Team     Engine     Team      Red       Chain       Team       Engine     Team       Loop
                                Team      Engine

Recon -- Scans the target to discover attack surface (open ports, SUID binaries, API endpoints, cloud metadata, CI/CD services, OSINT, fingerprinting)
Chain -- Attack chaining engine decides which exploits to run and in what order based on recon findings
Exploit -- Launches attacks matched to the target type (file reads, SQLi, path traversal, credential stuffing, pipeline poisoning, API fuzzing, protocol attacks)
Post-Exploit -- Executes post-exploitation techniques: lateral movement, persistence mechanisms, data exfiltration
Multi-Stage Chain -- Analyzes exploit results and chains follow-up attacks (e.g. SSH key harvest → lateral movement, shadow read → credential cracking)
Detect -- Sensors catch the attack in real-time (eBPF for syscalls, OTel trace collector for HTTP anomalies, platform audit log monitors, post-exploit behavior sensors)
Evaluate -- Policy engine scores the result and can kill malicious processes
Remediate -- Synthesizes a target-specific patch (AppArmor profile, WAF rule, Seccomp profile, Terraform snippet, K8s NetworkPolicy)
Validate -- Re-runs the original exploit against the patched target to confirm the remediation is effective

All components communicate asynchronously through NATS JetStream. Every event -- attacks, telemetry, remediations -- flows through the message broker as structured JSON.

Architecture

┌──────────────────────────────────────────────────────────────────────┐
│                         Control Plane                                │
│  ┌───────────────┐  ┌──────────────┐  ┌───────────────────────────┐  │
│  │ Orchestrator  │  │ Event Router │  │   Evaluation Engine       │  │
│  │ (Game Session)│  │   (NATS)     │  │   (Scoring + Chaining)    │  │
│  └──────┬────────┘  └──────┬───────┘  └───────────┬───────────────┘  │
│         │                 │                       │                  │
│  ┌──────┴────────┐  ┌─────┴──────┐  ┌─────────────┴───────────┐      │
│  │Patch Validator│  │ Dashboard  │  │   gRPC Plugin Server    │      │
│  │(Closed Loop)  │  │ (SSE/HTTP) │  │  (Out-of-process Extn)  │      │
│  └───────────────┘  └────────────┘  └─────────────────────────┘      │
│                                                                      │
├──────────────────── Message Broker (NATS) ───────────────────────────┤
│         │        ┌────────┴────────┐              │                  │
│         ▼        ▼                 ▼              ▼                  │
│  ┌──────────────────────────────────┐  ┌──────────────────────────┐  │
│  │         Red Team Mesh            │  │      Blue Team Mesh      │  │
│  │  ┌───────┐ ┌────────┐ ┌───────┐  │  │ ┌──────┐ ┌─────┐ ┌─────┐ │  │
│  │  │ Recon │ │Exploit │ │ Post  │  │  │ │ eBPF │ │ OTel│ │Polic│ │  │
│  │  │Modules│ │Modules │ │Exploit│  │  │ │Senso.│ │Coll.│ │Engi.│ │  │
│  │  │OSINT  │ │Go + Py │ │Lat.Mv │  │  │ │(C/Go)│ │     │ │     │ │  │
│  │  │Finger.│ │Nuclei  │ │Persis │  │  │ │PostEx│ │     │ │     │ │  │
│  │  └───────┘ └────────┘ │Exfilt │  │  │ │Sensor│ │     │ │     │ │  │
│  │                       └───────┘  │  │ └──────┘ └─────┘ └─────┘ │  │
│  └──────────────────────────────────┘  └──────────────────────────┘  │
│                                                                      │
│  ┌───────────────────────────────────────────────────────────────┐   │
│  │                Remediation Synthesizer                        │   │
│  │  AppArmor │ WAF │ Seccomp │ Terraform │ K8s │ sshd │ iptables │   │
│  └───────────────────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────────────────┘

Quick Start

Prerequisites

Go 1.25+
Podman (preferred) or Docker -- the runtime is auto-detected
podman-compose or docker-compose (for demo targets)
Python 3 (optional -- enables Python exploit modules)
kubectl (optional -- enables Kubernetes target modules)
aws CLI (optional -- enables AWS target modules)
nmap (optional -- enables network port scanning)
nikto, sqlmap (optional -- deeper web app scanning)
ssh-audit (optional -- SSH cipher/algorithm analysis)
nuclei (optional -- Nuclei vulnerability scanner for web app targets)
theHarvester, amass (optional -- OSINT reconnaissance)
protoc + protoc-gen-go + protoc-gen-go-grpc (optional -- only needed to regenerate proto stubs after editing uam.proto)

Run the Full Loop

# Clone
git clone https://github.com/abhikdps/universal-adversarial-mesh.git
cd universal-adversarial-mesh

# Start infrastructure + dashboard (builds containers, starts NATS)
./scripts/run.sh

# The dashboard opens at http://localhost:8080
# Trigger sessions against any target from the UI

Using the CLI

UAM supports two CLI styles: the run subcommand (recommended) and legacy flags.

# Build UAM
go build -o bin/uam ./cmd/uam

# Show help
./bin/uam help
./bin/uam run --help
./bin/uam target --help

# Run all targets from config
./bin/uam run --all --config configs/default.yaml

# Run specific targets
./bin/uam run --targets ssh,network --config configs/default.yaml

# Dashboard-only mode (no sessions on startup, trigger from UI)
./bin/uam run --dashboard 8080 --config configs/default.yaml

# Red team only
./bin/uam run --targets ssh --mode red

# Remediate a previous red team session
./bin/uam run --session <session-id>

# Full pipeline with dashboard
./bin/uam run --all --mode both --validate --dashboard 8080 --config configs/default.yaml

Target Management

Manage persistent targets stored in ~/.uam/targets.yaml:

# Add a target
./bin/uam target add --name "My SSH Server" --type ssh --endpoint localhost \
  --metadata "ssh_user=admin,ssh_port=22"

# List all targets
./bin/uam target list

# Remove a target
./bin/uam target remove target-ssh-my-ssh-server

Targets from ~/.uam/targets.yaml are merged with targets defined in the YAML config file. Container targets with a container_label metadata field have their endpoints auto-discovered from running containers.

Manual Run (Demo Targets)

# 1. Start infrastructure
podman-compose -f deployments/docker-compose.yml up -d

# 2. Build UAM
go build -o bin/uam ./cmd/uam

# 3. Run with all features
./bin/uam run --all --config configs/default.yaml --concurrent --validate --dashboard 8080

# 4. Cleanup
podman-compose -f deployments/docker-compose.yml down -v

Real-World Targets

# Kubernetes cluster (uses current kubectl context)
./bin/uam run --targets kubernetes --validate --dashboard 8080

# Web application (safe dry-run first)
./bin/uam run --targets app --config targets.yaml --dry-run

# SSH host
./bin/uam run --targets ssh --config targets.yaml --validate

# AWS account
./bin/uam run --targets aws --validate

# All targets from config file
./bin/uam run --all --config targets.yaml --concurrent --validate

CLI Reference

`uam run` flags

Flag	Default	Description
`--targets`		Comma-separated target IDs, names, or types to run
`--all`	`false`	Run all user-defined targets
`--config`		Path to YAML configuration file
`--session`		Source session ID to remediate (implies `--mode blue`)
`--mode`	`both`	Run mode: `red`, `blue`, or `both`
`--dashboard`	`0`	Dashboard port (0 = disabled)
`--concurrent`	`false`	Run sessions concurrently
`--validate`	`false`	Re-run exploits after patching to validate remediation
`--dry-run`	`false`	Log actions without executing destructive exploits
`--watch`		Watch mode interval (e.g. `5m`, `1h`)
`--watch-targets`		Comma-separated target IDs or types to watch
`--output`		Output directory (overrides config)
`--json-log`	`false`	Use JSON structured logging
`--log-level`	`info`	Log level: `debug`, `info`, `warn`, `error`
`--plugins-dir`		Directory containing `.plugin` descriptor files for remote plugins

Legacy flags (without subcommand)

Flag	Default	Description
`-target`	`all`	Target type filter: `infra`, `app`, `platform`, `kubernetes`, `ssh`, `aws`, `container`, `network`, or `all`
`-nats`	`nats://localhost:4222`	NATS server URL
`-output`	`./output`	Directory for session result JSON files
`-config`		Path to YAML configuration file
`-concurrent`	`false`	Run sessions concurrently
`-validate`	`false`	Re-run exploits after patching to validate remediation
`-dry-run`	`false`	Log actions without executing destructive exploits
`-json-log`	`false`	Use JSON structured logging (slog)
`-dashboard`	`0`	Dashboard port (0 = disabled)
`-mode`	`both`	Run mode: `red` (attack only), `blue` (remediate only), or `both`
`-watch`		Watch mode interval (e.g. `5m`, `1h`). Re-runs sessions on this schedule
`-watch-targets`		Comma-separated target IDs or types to watch
`-log-level`	`info`	Log level: `debug`, `info`, `warn`, `error`
`-plugins-dir`		Directory containing `.plugin` descriptor files for remote plugins

Features

Attack Chaining

The attack chain engine uses recon findings to intelligently select and order exploits:

Infra: readable /etc/shadow triggers file-read exploits; SUID binaries trigger privilege escalation; root context boosts all priorities
App: SQL error messages trigger SQLi exploits; search endpoints trigger both Go and Python fuzzers; login endpoints trigger credential stuffing; reflected input triggers XSS; exposed .env/.git triggers traversal
Platform: Jenkins/GitLab endpoints trigger pipeline poisoning; cloud metadata endpoints trigger SSRF; auth endpoints trigger credential stuffing
Kubernetes: cluster-admin bindings trigger RBAC escalation; privileged pods trigger container escape; missing network policies trigger lateral movement
SSH: sudo NOPASSWD triggers privilege escalation; weak ciphers and PermitRootLogin trigger hardening checks
AWS: overpermissive IAM triggers escalation; public S3 buckets trigger data exfiltration; IMDSv1 triggers credential harvesting
Container: Docker socket mount triggers escape; all-capabilities triggers privileged breakout; seccomp disabled triggers expanded surface
Network: Redis/MongoDB/MySQL triggers default credential probes; open ports trigger service version checks

Multi-Stage Chaining

After the initial exploit phase, a second chaining pass analyzes successful attack results to chain follow-up exploits:

SSH key harvest → lateral movement for key reuse across hosts
Shadow file read → credential attack for hash cracking
Container escape → lateral movement for container-to-container pivoting
SSRF success → advanced web app attacks on discovered internal endpoints
Default credential success → lateral movement for credential reuse
DNS exfiltration → expanded exfiltration channel testing

Multi-stage chaining is bounded to a single additional pass to prevent runaway chains. Already-executed exploits are deduplicated.

Post-Exploitation

Post-exploitation modules execute after successful exploits to demonstrate real-world impact:

Module	Techniques
Lateral Movement	SSH key reuse, credential pivoting, container-to-container movement, network service hopping
Persistence	Cron job implants, SSH authorized_keys injection, systemd service creation, shell profile backdoors
Exfiltration	DNS tunneling, HTTP(S) staging, file archival, cloud storage upload simulation

Post-exploitation results feed back into the multi-stage chaining engine and are monitored by the post-exploit behavior sensor.

Run Modes

UAM supports three run modes via --mode, orthogonal to --dry-run:

Mode	Red Team	Blue Team	Use Case
`both` (default)	Recon + Exploit	Sensors + Remediation + Validation	Full adversarial loop
`red`	Recon + Exploit	Skipped	Attack-only assessment
`blue`	Skipped	Recon + Remediation from findings	Scan-and-fix without active attacks

# Red team only -- attack and report
./bin/uam run --targets ssh --mode red

# Blue team only -- scan for vulnerabilities and generate patches
./bin/uam run --targets network --mode blue

# Passive recon only (red + dry-run)
./bin/uam run --targets kubernetes --mode red --dry-run

# Full pipeline (default)
./bin/uam run --all --mode both --validate --dashboard 8080

In blue-only mode, recon findings are converted to synthetic attack events so the remediation engine can generate patches without running active exploits.

In red-only mode, detection rate, remediation rate, and overall score display as "N/A" in the dashboard since no blue team sensors are running.

Remediate from Previous Session

Run blue team remediation against real attack findings from a previous red team session, rather than synthesized findings from recon:

# First, run red team
./bin/uam run --targets ssh --mode red --config configs/default.yaml
# Note the session ID from the output

# Then, remediate using real attack events from that session
./bin/uam run --session <session-id>

This can also be triggered from the dashboard UI: completed red-only sessions show a "Run Blue Team" button that starts a remediation session using the original attack events.

The remediation session is linked to its source via parent_session_id and appears as a separate blue-mode session in the sidebar.

Concurrent Sessions

Run multiple target sessions in parallel with --concurrent. Each session operates independently with its own event stream, scoring, and remediation.

Patch Validation (Closed Loop)

With --validate, UAM applies the generated patch to the target and re-runs the original exploit to confirm the vulnerability is fixed. The validation result (PASSED/FAILED) is recorded in the session output.

Live Dashboard

Enable with --dashboard 8080. The embedded HTTP server provides:

Real-time event timeline via Server-Sent Events (SSE) with 30s heartbeat and 5min idle timeout
Session scores with circular progress rings (detection rate, remediation rate, overall score)
Session sidebar with mode badges (RED/BLUE/BOTH) and run status
"Run Blue Team" button for remediating completed red sessions
Target cards for launching sessions against individual targets
Configuration panel for changing run mode, concurrency, and validation at runtime
Error events displayed in timeline when recon/exploits fail
Resizable sidebar for viewing long session names
Plugin registry viewer at GET /api/v1/plugins (lists all registered local and remote plugins)
Health check endpoint at GET /healthz (no auth required)
Prometheus metrics at GET /metrics
Versioned API under /api/v1/ with backward-compatible redirects from /api/
Dark-themed single-page application

Dashboard-only mode: Start the dashboard without running any sessions on startup. Targets are loaded from the config and displayed as cards -- trigger sessions on demand from the UI.

./bin/uam run --dashboard 8080 --config configs/default.yaml

Dry-Run Mode

Run with --dry-run to audit without executing destructive exploits. Modules implementing the DryRunnable interface will log what they would do instead of executing. Recon is always read-only regardless of dry-run mode.

./bin/uam run --targets kubernetes --dry-run --validate --dashboard 8080

Watch Mode (Continuous Monitoring)

Run with --watch to turn UAM into a long-running service that re-runs sessions on a schedule. The dashboard is auto-enabled in watch mode and shows a live countdown to the next run.

# Re-run all sessions every 5 minutes
./bin/uam run --all --watch 5m --concurrent

# Continuous blue-only scan every hour
./bin/uam run --targets network --watch 1h --mode blue

# Fast red team sweep every 30 seconds (testing)
./bin/uam run --targets ssh --watch 30s --mode red

Combinable with all other flags (--mode, --dry-run, --concurrent, --validate). Each run produces independent sessions with unique IDs, all visible in the dashboard sidebar. Press Ctrl+C for clean shutdown.

Input Validation

All target endpoints are validated before use based on target type:

Target Type	Validation Rules
SSH	Rejects shell metacharacters (; & \| $ `), validates host format
Network	Accepts CIDR notation, `host:port`, or bare IP/hostname
Container	Alphanumeric with hyphens, underscores, dots only
Application/Platform	Requires `http://` or `https://` scheme
Kubernetes	Kubernetes-safe characters only

Invalid endpoints are rejected at config load and via the target add CLI before any session runs.

Observability

Correlation IDs -- Every event (attack, telemetry, remediation) in a session shares a correlation_id, enabling end-to-end tracing across the distributed event flow from exploit to detection to patch.

Prometheus Metrics -- Available at GET /metrics in Prometheus text format:

Metric	Type	Description
`uam_sessions_total`	Counter	Total sessions started
`uam_attacks_total`	Counter	Total attacks launched
`uam_attacks_succeeded`	Counter	Successful attacks
`uam_remediations_total`	Counter	Total remediations generated
`uam_remediations_applied`	Counter	Remediations applied
`uam_session_duration_seconds`	Histogram	Session duration (buckets: 1s to 10min)

Structured Logging -- Configurable log levels via --log-level (debug, info, warn, error) with JSON or text output. All log entries include structured fields (component, session ID, module name).

Structured Errors -- Errors carry operation context (UAMError with Op, SessionID, Module fields) and wrap sentinel errors (ErrSessionTimeout, ErrBrokerDisconnected, ErrInvalidTarget) for programmatic handling.

Session Persistence

UAM supports two persistence backends, used simultaneously when both are configured:

Backend	When Used	What It Stores
File (default)	Always	JSON files in `./output/` (optionally encrypted)
PostgreSQL (optional)	When `database.dsn` or `UAM_DATABASE_DSN` is set	Normalized tables with JSONB for targets, scores, and event payloads

Setup:

# 1. Create a PostgreSQL database
createdb uam

# 2. Set the connection string (or add database.dsn to config YAML)
export UAM_DATABASE_DSN="postgres://user:pass@localhost:5432/uam?sslmode=disable"

# 3. Run UAM -- tables are auto-created on first run
./bin/uam run --all --config configs/default.yaml

When Postgres is configured, sessions are written to both the database (for querying) and files (for export/sharing). If Postgres is unreachable at startup, UAM falls back to file-only with a warning. The in-memory cache is used for hot reads during runtime -- the database is for persistence across restarts.

# Query session history directly
psql uam -c "SELECT id, state, target->>'name', started_at FROM sessions ORDER BY started_at DESC"

Reliability

Session timeouts -- Configurable per-session timeout (default 5 minutes, set via session_timeout in config). Sessions are cancelled gracefully via context on timeout.
Atomic file writes -- Session data is written to a temp file, then atomically renamed to the final path to prevent corruption on crash or power loss.
File permissions -- Session output files are created with 0600 permissions (owner read/write only).

Role-Based Access Control (RBAC)

The dashboard API supports multi-key RBAC with three roles:

Role	Read (sessions, events, targets, config)	Operate (start sessions, remediate, apply patches)	Admin (modify config, manage targets, control watch)
viewer	yes	no	no
operator	yes	yes	no
admin	yes	yes	yes

Public endpoints (/, /healthz, /metrics) bypass auth entirely.

Configuration:

dashboard:
  enabled: true
  port: 8080
  rbac:
    keys:
      - name: "admin-key"
        key: "your-admin-secret"
        role: "admin"
      - name: "ops-key"
        key: "your-ops-secret"
        role: "operator"
      - name: "readonly-key"
        key: "your-viewer-secret"
        role: "viewer"

Keys are passed via Authorization: Bearer <key> header or ?api_key=<key> query param. Invalid keys return 401; valid keys with insufficient role return 403 with the required role in the response body.

Backward compatible -- the legacy single api_key field still works and is treated as admin. If neither rbac nor api_key is set, auth is disabled.

All mutating API calls (start session, modify config, manage targets) are audit-logged with the key name, role, and remote address.

Python Exploit Library

Three Python exploit scripts are auto-discovered and registered as exploit modules when Python 3 is available:

Script	Description
`sqli_fuzzer.py`	7 SQLi techniques, multiple injection points
`path_traversal.py`	16+ encoding bypasses, 12 sensitive files
`credential_stuffer.py`	31 credential pairs, JSON/form-encoded

OpenTelemetry Trace Collector

Real OTLP-compatible HTTP collector at /v1/traces that receives spans and detects:

SQL errors in error spans (SQLi)
Abnormal latency > 5s (time-based SQLi)
Path traversal patterns in URLs
HTTP 500 spikes
Shell spawns from web handlers

eBPF Probes (Linux)

Real BPF tracepoint programs for kernel-level monitoring:

file_open.c -- tracepoint on sys_enter_openat, monitors access to sensitive files
exec_monitor.c -- tracepoint on sys_enter_execve, detects unexpected process execution
Go loader using cilium/ebpf with perf buffer reading
macOS stub that falls back to container audit hooks

gRPC Plugin Architecture

Out-of-process plugin support via gRPC for all module types. The proto contract is defined in api/proto/uam.proto with generated Go stubs in api/gen/uam/v1/. Plugins can be written in any language that supports gRPC.

Four plugin services:

SensorPlugin -- blue-team sensor (Start, Stop, StreamTelemetry server-streaming RPC)
ExploitPlugin -- red-team exploit module (Execute, Info)
ReconPlugin -- reconnaissance module (Scan)
RemediationPlugin -- patch generation (GeneratePatch)

Features:

Remote adapters (RemoteSensor, RemoteExploitModule, RemoteReconModule, RemoteRemediationEngine) wrap gRPC clients as local interfaces -- the orchestrator treats them identically to in-process modules
Plugin registry with file-based discovery (.plugin descriptors in --plugins-dir)
Automatic connection: descriptors are loaded at startup, remote plugins are dialed and registered
Dashboard API: GET /api/v1/plugins lists all registered plugins (local + remote) with metadata
SHA-256 checksum verification for plugin scripts (optional, via config)
TLS support for gRPC connections (CA certificate via plugins.tls_ca_file config, insecure fallback)

Plugin descriptor format (.plugin files):

name=my-exploit
kind=exploit
addr=localhost:50052
target_type=infrastructure

Regenerating proto stubs (after editing uam.proto):

# Install tools (one-time)
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

# Generate
protoc --go_out=api/gen --go_opt=paths=source_relative \
       --go-grpc_out=api/gen --go-grpc_opt=paths=source_relative \
       --proto_path=api/proto uam.proto

YAML Configuration

Externalized configuration via YAML for all settings:

nats:
  url: nats://localhost:4222
concurrent: true
validate_patches: true
dry_run: false
run_mode: both  # red | blue | both
watch:
  enabled: false
  interval: "5m"    # Go duration format (5m, 1h, 30s, 2h30m)
dashboard:
  enabled: true
  port: 8080
  # api_key: "single-shared-key"          # legacy single key (treated as admin)
  rbac:                                    # multi-key RBAC (overrides api_key)
    keys:
      - name: admin-key
        key: "change-me-admin"
        role: admin
      - name: ops-key
        key: "change-me-ops"
        role: operator
      - name: viewer-key
        key: "change-me-viewer"
        role: viewer
targets:
  - id: my-k8s-cluster
    name: Production K8s
    type: kubernetes
    endpoint: ~/.kube/config
  - id: my-webapp
    name: Internal Portal
    type: application
    endpoint: https://portal.corp.local
  - id: staging-ssh
    name: Staging Jump Box
    type: ssh
    endpoint: admin@10.0.1.50
    metadata:
      ssh_key_path: ~/.ssh/id_rsa
      ssh_port: "22"
  - id: aws-staging
    name: AWS Staging Account
    type: aws
    metadata:
      aws_profile: staging
      aws_region: us-east-1
  - id: redis-host
    name: Cache Server
    type: network
    endpoint: 10.0.2.100
  - id: my-container
    name: App Container
    type: container
    metadata:
      container_label: "uam-target=infra"  # auto-discovers running container ID
sensors:
  ebpf:
    enabled: true
    watch_files: ["/etc/shadow", "/etc/passwd"]
  otel:
    enabled: true
chaining:
  enabled: true
modules:                                   # opt-out: all default to true
  kubernetes: true
  ssh: true
  aws: true
  container: true
  network: true
  osint: true                              # OSINT recon (theHarvester, amass)
  fingerprint: true                        # service fingerprinting + CVE lookup
  web_advanced: true                       # advanced web app attacks (API fuzzing, SSRF)
  api_fuzzing: true                        # API endpoint fuzzing
  credential_attack: true                  # credential spraying + hash cracking
  post_exploit: true                       # lateral movement, persistence, exfiltration
  nuclei: true                             # Nuclei vulnerability scanner (requires nuclei binary)
reporting:
  format: text                             # text | json | markdown | all
  compliance: []                           # pci-dss, hipaa, soc2, nist, cis
plugins:
  dir: ""                                  # directory containing .plugin descriptor files
  tls_ca_file: ""                          # CA certificate for gRPC TLS connections
  checksums:                               # optional: SHA-256 checksums for Python exploit scripts
    sqli_fuzzer.py: "a1b2c3..."
    path_traversal.py: "d4e5f6..."
# encryption_key: ""                      # optional: set via UAM_ENCRYPTION_KEY env var instead

Real-World Target Support

UAM supports 8 target types across infrastructure, applications, cloud, and network layers. Modules are tool-gated: if a required CLI tool isn't installed, the module is skipped gracefully. webapp is an alias for application -- both use the same target type with multiple specialized modules.

Target Type	CLI Flag	Required Tools	Recon	Exploit	Post-Exploit	Remediation
Infrastructure	`infra`	podman/docker	File permissions, SUID, ports, OSINT, fingerprinting	Sensitive file read	Persistence, exfiltration	AppArmor profile
Application	`app` / `webapp`	nikto, sqlmap, nuclei (optional)	HTTP endpoints, SQLi probing, security headers, crawl, OSINT	SQLi, XSS, path traversal, SSRF, API fuzzing, Nuclei scan	Exfiltration	WAF rules, ModSecurity rules
Platform	`platform`		CI/CD, cloud metadata, IAM	Credential stuffing, pipeline poisoning	Persistence	Terraform snippets
Kubernetes	`kubernetes`	kubectl	Namespaces, RBAC, pods, secrets, network policies	RBAC escalation, secret listing	Lateral movement	K8s NetworkPolicy
SSH	`ssh`	ssh, ssh-audit (optional)	Banner, sudo, SUID, sshd_config, OSINT	Privilege escalation, key harvesting, credential attack	Lateral movement, persistence	sshd_config hardening
AWS	`aws`	aws	IAM, S3, EC2, IMDS	IAM escalation, S3 exfil, IMDS harvest	Exfiltration	IAM deny policies
Container	`container`	podman/docker	Capabilities, seccomp, mounts, namespaces	Docker socket escape, secret harvesting	Lateral movement, persistence	Seccomp profile, hardening policy
Network	`network`	nmap (optional)	Port scan, service detection, banners, advanced protocol analysis	Default credential probes, protocol fuzzing, service exploitation	Lateral movement	Firewall rules (iptables)

Project Structure

.
├── .github/workflows/                # CI/CD pipelines
│   ├── unit-tests.yml                # Unit tests + lint
│   ├── integration-tests.yml         # End-to-end with Docker Compose
│   └── build.yml                     # Cross-platform build + Docker images
├── cmd/uam/                          # Entry point
│   ├── main.go                       # CLI entry point, config loading, setupAndRun
│   ├── run.go                        # Run + remediate subcommands, module registration
│   ├── target.go                     # Target add/list/remove subcommands
│   └── helpers.go                    # Target aliases, filtering, resolution, reporting
├── api/
│   ├── proto/                        # Protobuf service definitions
│   │   └── uam.proto
│   └── gen/uam/v1/                   # Generated Go stubs (protoc-gen-go + protoc-gen-go-grpc)
│       ├── uam.pb.go                 # Message types (TargetProfile, AttackEvent, etc.)
│       └── uam_grpc.pb.go            # gRPC client/server stubs for all 4 plugin services
├── configs/
│   └── default.yaml                  # Default YAML configuration
├── internal/
│   ├── orchestrator/                 # Session lifecycle, attack chaining, patch validation
│   │   ├── orchestrator.go           # Core struct, setters, RunAll, StartSession, sensors
│   │   ├── session.go               # Session execution, event handlers, RemediateFromSession
│   │   ├── persistence.go           # Session load/save, GetSession, GetAllSessions
│   │   ├── chaining.go              # Attack chain decision engine
│   │   └── validator.go             # Patch validation (closed loop)
│   ├── broker/                       # NATS message broker
│   ├── events/                       # Event router and publish helpers
│   ├── dashboard/                    # Embedded HTTP server + SSE dashboard
│   │   ├── server.go                # Core types, constructor, Start, CORS middleware
│   │   ├── handlers.go              # All HTTP/REST handlers
│   │   ├── events.go                # Session/event management, watch state, SSE broadcast
│   │   ├── helpers.go               # JSON errors, type validation, persistence utilities
│   │   └── index.html               # Dark-themed SPA with resizable sidebar
│   ├── plugins/                      # gRPC plugin hosting (uses generated stubs from api/gen/)
│   │   ├── grpc_server.go           # Plugin server, service impls, proto ↔ types converters
│   │   ├── grpc_client.go           # Remote*Module adapters (sensor, exploit, recon, remediation)
│   │   ├── registry.go              # Plugin registry, discovery, remote connection
│   │   └── verify.go                # SHA-256 checksum verification
│   ├── blueteam/
│   │   ├── ebpf/                    # eBPF sensors
│   │   │   ├── file_sensor.go       # Container audit hook sensor
│   │   │   ├── bpf_loader.go        # Linux: real cilium/ebpf loader
│   │   │   ├── bpf_loader_stub.go   # macOS: no-op stub
│   │   │   └── probes/              # C BPF programs
│   │   │       ├── file_open.c      # sys_enter_openat tracepoint
│   │   │       └── exec_monitor.c   # sys_enter_execve tracepoint
│   │   ├── otel/                    # OpenTelemetry sensors
│   │   │   ├── http_sensor.go       # HTTP request log poller
│   │   │   └── collector.go         # OTLP trace collector + anomaly detection
│   │   ├── policy/                  # Rule-based policy engine
│   │   ├── sensor/                  # Platform + behavior sensors
│   │   │   ├── platform_sensor.go   # Platform audit log monitor
│   │   │   ├── behavior_sensor.go   # Runtime behavior anomaly detection
│   │   │   └── postexploit_sensor.go # Post-exploitation activity detector
│   │   ├── ssh/                     # SSH sensors (auth, credential)
│   │   ├── network/                 # Network sensors (flow, packet)
│   │   ├── webapp/                  # Web app sensors (request, advanced)
│   │   └── container/               # Container sensors (escape, privilege)
│   ├── redteam/
│   │   ├── recon/                   # Recon modules
│   │   │   ├── infra_recon.go       # Container recon (files, SUID, ports)
│   │   │   ├── app_recon.go         # HTTP endpoint discovery + SQLi probing
│   │   │   ├── platform_recon.go    # CI/CD, cloud metadata, IAM scanning
│   │   │   ├── k8s_recon.go         # Kubernetes RBAC, pods, network policies
│   │   │   ├── webapp_recon.go      # Advanced web app crawl + security headers (application type)
│   │   │   ├── ssh_recon.go         # SSH banner, sudo, sshd_config analysis
│   │   │   ├── aws_recon.go         # AWS IAM, S3, EC2, IMDS scanning
│   │   │   ├── container_recon.go   # Capabilities, seccomp, mounts, namespaces
│   │   │   ├── network_recon.go     # Port scan + service detection (nmap/fallback)
│   │   │   ├── network_advanced_recon.go # Protocol analysis + service fingerprinting
│   │   │   ├── osint_recon.go       # OSINT gathering (theHarvester, amass, WHOIS)
│   │   │   └── fingerprint_recon.go # Service fingerprinting + CVE lookup
│   │   ├── exploit/                 # Exploit modules
│   │   │   ├── infra_exploit.go     # File read exploit
│   │   │   ├── app_exploit.go       # SQLi + path traversal
│   │   │   ├── platform_exploit.go  # Credential stuffing + pipeline poisoning
│   │   │   ├── k8s_exploit.go       # RBAC escalation + secret listing
│   │   │   ├── webapp_exploit.go    # SQLi, XSS, traversal, SSRF (application type)
│   │   │   ├── webapp_advanced_exploit.go # API fuzzing + advanced injection
│   │   │   ├── ssh_exploit.go       # Privilege escalation + key harvesting
│   │   │   ├── aws_exploit.go       # IAM escalation + S3 exfil + IMDS
│   │   │   ├── container_exploit.go # Docker socket escape + secret harvesting
│   │   │   ├── network_exploit.go   # Default credential probes
│   │   │   ├── network_advanced_exploit.go # Protocol fuzzing + service exploitation
│   │   │   ├── credential_exploit.go # Credential spraying + hash cracking
│   │   │   ├── nuclei_exploit.go    # Nuclei vulnerability scanner integration
│   │   │   ├── api_fuzzer.go        # API endpoint fuzzing
│   │   │   └── python_runner.go     # Python subprocess runner + discovery
│   │   └── postexploit/             # Post-exploitation modules
│   │       ├── lateral_movement.go  # SSH key reuse, credential pivoting, network hopping
│   │       ├── persistence.go       # Cron jobs, SSH keys, systemd services, shell profiles
│   │       └── exfiltration.go      # DNS tunneling, HTTP staging, cloud upload simulation
│   └── remediation/                 # Polyglot patch synthesizer
│       └── synthesizer.go           # AppArmor, WAF, Seccomp, Terraform, K8s,
│                                    # ModSecurity, sshd_config, firewall rules
├── pkg/
│   ├── types/                       # Shared types, validation, and structured errors
│   ├── config/                      # YAML config loader + target management
│   ├── container/                   # Podman/Docker runtime abstraction
│   ├── crypto/                      # AES-256-GCM encryption for session data at rest
│   ├── cvedb/                       # CVE database client for vulnerability lookups
│   ├── metrics/                     # Prometheus-compatible counters and histograms
│   ├── tools/                       # External tool detection (kubectl, nmap, nuclei, etc.)
│   └── logging/                     # Structured logging (slog) with configurable levels
├── scripts/
│   ├── run.sh                       # One-command startup (infra + dashboard)
│   └── exploits/                    # Python exploit scripts
│       ├── sqli_fuzzer.py
│       ├── path_traversal.py
│       └── credential_stuffer.py
├── deployments/
│   ├── docker-compose.yml           # NATS + target containers
│   ├── targets/
│   │   ├── vulnerable-infra/        # Ubuntu with weak permissions
│   │   └── vulnerable-app/          # Express API with SQLi
│   └── k8s/                         # Kubernetes manifests
│       ├── deployment.yaml
│       └── network-policy.yaml
└── output/                          # Session result JSON artifacts

Testing

# Run all unit tests
go test ./...

# Run with verbose output and race detection
go test -v -race ./...

# Run a specific package
go test ./internal/orchestrator/... -v

# Run with coverage
go test -coverprofile=coverage.out ./...
go tool cover -func=coverage.out

Test coverage (376 tests across 19 suites):

Package	Tests	What's Covered
`pkg/types`	49	ScoreCard calculation, JSON serialization, validation, structured errors, target types
`pkg/config`	23	Default values, YAML loading, error cases, target parsing, target management, module config
`pkg/cvedb`	10	CVE database lookups, caching, error handling
`pkg/metrics`	12	Prometheus counters, histograms, text output
`pkg/crypto`	14	AES-256-GCM encryption/decryption, key derivation, error cases
`internal/remediation`	7	Patch generation across all target types
`internal/events`	12	Event router, handler registration, idempotent subscribe, publish helpers
`internal/orchestrator`	46	Full session lifecycle, sequential/concurrent runs, multi-stage chaining, post-exploit integration
`internal/blueteam/otel`	17	All 5 anomaly detectors, HTTP handler, edge cases
`internal/blueteam/policy`	7	All policy rules, partial matching, default action
`internal/blueteam/sensor`	13	Behavior sensor, post-exploit sensor, anomaly detection
`internal/blueteam/webapp`	7	Web app sensor, request analysis
`internal/dashboard`	54	Session management, event buffer, HTTP endpoints, SSE, target CRUD, config, plugins API
`internal/plugins`	15	Registry, discovery, remote connection, plugin descriptors
`internal/redteam/exploit`	28	All exploit modules, dry-run, credential attacks, API fuzzing, network advanced
`internal/redteam/recon`	30	All recon modules, OSINT, fingerprinting, network advanced
`internal/redteam/postexploit`	10	Lateral movement, persistence, exfiltration techniques
`internal/store`	10	File store, postgres store, composite store
`internal/reporting`	12	Report generation, compliance formatting

CI/CD

GitHub Actions workflows run automatically on pushes and PRs to main:

Workflow	File	What It Does
Unit Tests	`.github/workflows/unit-tests.yml`	`go test -race`, `go vet`, `gofmt` check, coverage report
Integration Tests	`.github/workflows/integration-tests.yml`	Spins up the full Docker Compose stack and runs UAM against real targets (red-only, blue-only, full pipeline, dry-run)
Build	`.github/workflows/build.yml`	Cross-platform binary build (Linux + macOS), Docker image build

Plugin Architecture

All Red and Blue team capabilities are defined as Go interfaces in pkg/types/interfaces.go. Adding a new module requires implementing one interface -- no orchestrator changes needed.

Adding a Red Team Module

Implement ExploitModule:

type ExploitModule interface {
    Name() string
    TargetType() TargetType
    Execute(ctx context.Context, target TargetProfile, sessionID string) (*AttackEvent, error)
}

Register in main.go:

orch.RegisterExploit(mymodule.NewMyExploit())

Or deploy as a gRPC plugin by implementing the ExploitPlugin service from api/proto/uam.proto -- no code changes to UAM itself, any language supported.

Adding a Blue Team Sensor

Implement Sensor:

type Sensor interface {
    Name() string
    TargetType() TargetType
    Start(ctx context.Context, sessionID string) error
    Stop() error
}

Sensors publish TelemetryEvent messages to the NATS uam.telemetry subject. The orchestrator picks them up automatically.

Adding a Remediation Generator

Implement the PatchGenerator interface and register it in the Synthesizer for your target type. The synthesizer routes to the correct generator based on TargetType.

Included Targets

Target 1: Vulnerable Ubuntu Container (Infrastructure)

World-readable /etc/shadow
SUID binary (/usr/bin/find)
Sensitive data in /root/.env and /root/.ssh/id_rsa
Test user with weak password

Attack: Unauthorized file read of /etc/shadow Detection: eBPF file access sensor catches the read via audit hooks Remediation: Generates an AppArmor profile denying access to sensitive files Validation: Re-runs file read after chmod 600 -- confirms access denied

Target 2: Vulnerable Express API (Application)

SQL injection in /api/users/:id, /api/users/search, /api/login
Path traversal in /api/files
Verbose SQL error messages in responses

Attack: UNION-based SQL injection against /api/users/search Detection: OTel HTTP sensor and trace collector match SQLi patterns Remediation: Generates a WAF JSON rule blocking SQLi payloads Validation: Re-runs SQLi payload -- confirms WAF blocks the request

Target 3: Platform / CI-CD (Platform)

CI/CD endpoints (Jenkins, GitLab)
Cloud metadata endpoints
Login endpoints with default credentials

Attack: Credential stuffing and pipeline poisoning Detection: Platform audit log sensor detects unauthorized API calls and config changes Remediation: Generates Terraform snippets for IAM hardening

Output

Each session produces a structured JSON file in ./output/ containing (optionally encrypted at rest via AES-256-GCM when UAM_ENCRYPTION_KEY is set):

Target profile and metadata
Session lineage (run_mode, parent_session_id for remediation sessions)
Full event timeline (attacks, telemetry, remediations, validations, errors)
Generated patch content (AppArmor profiles, WAF rules, Seccomp, Terraform, K8s NetworkPolicy, ModSecurity rules, sshd_config, firewall rules)
Scoring: detection rate, remediation rate, overall score
Patch validation results (PASSED/FAILED)

Technology Stack

Component	Technology
Core engines	Go (with `log/slog` structured logging)
Message broker	NATS JetStream
Infra sensors	eBPF (C tracepoints + Go `cilium/ebpf` loader)
App sensors	OpenTelemetry-compatible OTLP trace collector
Platform sensors	HTTP audit log monitoring
Container runtime	Podman (primary) / Docker (fallback)
Target environments	Podman/Docker Compose, Kubernetes
Exploit scripts	Go + Python 3 (auto-discovered) + external tools (nmap, nikto, sqlmap, ssh-audit, nuclei)
Plugin system	gRPC with optional TLS (out-of-process extensions)
Metrics	Prometheus-compatible (zero-dependency counters + histograms)
Encryption	AES-256-GCM with PBKDF2 key derivation (session data at rest)
Configuration	YAML
Dashboard	Embedded HTTP + SSE (dark-themed SPA)
Vulnerable app	Node.js / Express / SQLite

Design Principles

Target-agnostic: The orchestrator doesn't know how to attack or defend -- modules do. Adding AWS support means adding a module, not changing the core.
Event-driven: No blocking calls between Red and Blue teams. All state flows through NATS.
Closed-loop validation: Patches aren't trusted until the original exploit fails against them.
Dry-run safe: Every exploit module supports dry-run mode via the DryRunnable interface -- audit without risk.
Tool-gated: Modules that require external tools (kubectl, nmap, aws, nuclei) are automatically skipped if the tool isn't installed.
Configurable modules: Individual capability modules (OSINT, fingerprinting, post-exploitation, Nuclei, etc.) can be enabled/disabled via YAML config -- opt-out model with all enabled by default.
Idempotent remediation: Every generated patch (AppArmor, WAF, Seccomp, Terraform, K8s NetworkPolicy, sshd_config, firewall rules) is safe to apply repeatedly.
Runtime-agnostic: Podman and Docker are both supported via the container runtime abstraction layer.
Validated inputs: All target endpoints are type-checked before use -- SSH rejects shell metacharacters, network validates CIDR/host:port, URLs require http(s).
Resilient: Session timeouts with graceful cancellation, atomic file writes for crash safety, structured errors with operation context for debugging.
Extensible: gRPC plugin interfaces (with TLS) allow out-of-process extensions in any language without touching UAM core. SHA-256 checksum verification for plugin scripts.
Observable: Correlation IDs across all events, Prometheus metrics, configurable structured logging via slog, live dashboard with SSE, and comprehensive session artifacts.
Secure at rest: Optional AES-256-GCM encryption for session output files containing sensitive findings.

Disclaimer

This tool is intended for authorized security testing and educational purposes only. Users are solely responsible for obtaining proper authorization before testing any systems. Unauthorized access to computer systems is illegal. The authors assume no liability for misuse of this software.

Always obtain written permission from the system owner before running UAM against any target. Use the --dry-run flag for read-only audits when in doubt.

License

MIT - see LICENSE for details.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
api		api
cmd/uam		cmd/uam
configs		configs
deployments		deployments
internal		internal
pkg		pkg
scripts		scripts
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
go.mod		go.mod
go.sum		go.sum

Latest commit

History

Folders and files

Repository files navigation