Security Automation Gateway (SAG)

Secure gateway for automation engine access — ABAC policies, human-in-the-loop approvals, immutable audit, and SDK wrappers for MCP, n8n, Zapier, and custom engines.

Language	Python 3.14
Framework	FastAPI + Uvicorn
Services	15 backend microservices + Service Console
Status	Alpha — active development

---

What It Does

SAG sits between users/automation clients and automation engines. Every request passes through authentication, policy evaluation, optional approval workflows, and execution-context isolation before an adapter runs the action. All decisions are logged for compliance (SOC2 / ISO 27001 ready).

Core capabilities

• Zero-trust entry — API Gateway validates, rate-limits, and proxies to backends
• ABAC — Attribute-based access control via Open Policy Agent (OPA)
• Approvals — Multi-level workflow engine with escalation and delegation
• Execution isolation — Permission-set impersonation, credential vaulting, sandboxed runs
• Audit & SIEM — Tamper-evident logs, CEF output, real-time event streaming
• Operations — Service Console (topology + secrets UI), monitoring, policy admin

---

Architecture (Quick View)

Clients / SDKs
      │
      ▼
┌─────────────┐     ┌──────────────────────────────────────────┐
│ API Gateway │────▶│ Security: Auth · Identity · Policy (PDP) │
│  :8004      │     └──────────────────────────────────────────┘
└─────────────┘                    │
      │                            ▼
      │              ┌─────────────────────────────┐
      └─────────────▶│ Orchestrator · Workflow ·   │
                     │ Notification · Execution    │
                     └─────────────────────────────┘
                                   │
                     ┌─────────────┴─────────────┐
                     ▼                           ▼
              Adapter Framework            Audit · SIEM · Monitoring
                     │
                     ▼
           MCP · n8n · Zapier · Custom

Full diagrams (context, sequence, entity-relationship): see ARCHITECTURE.md

Why we chose this stack: see ADR.md

---

Services & Ports

Service	Port	Role
auth-service	8001	Login, tokens, MFA, pluggable IdP
adapter-framework	8002	MCP / n8n / Zapier adapters
audit-service	8003	Immutable audit trail
api-gateway	8004	Entry point, proxy /v1/<service>/*
execution-context	8005	Sandboxed execution, vaulting
identity-service	8006	Users, attributes, permission-sets
monitoring-service	8007	Metrics, alerts, dashboards
notification-service	8008	Email / webhook / in-app alerts
orchestrator-service	8009	Request state machine, risk scoring
policy-service	8010	ABAC policy evaluation (PDP)
policy-admin-service	8011	Policy lifecycle, testing, deploy
security-hardening	8012	Hardening checks & controls
admin-console	8013	Admin UI API
siem-integration	8014	CEF events, SIEM forwarding
workflow-service	8015	Approval workflows
console-service	8020	Service topology & secrets UI

Canonical endpoint list: ENDPOINTS_INVENTORY.md

Gateway routes: /v1/auth/*, /v1/identity/*, /v1/policy/*, etc. — same path forwarded to backend with service token.

---

Quick Start

Prerequisites

• Docker & Docker Compose
• Python 3.11+ (3.14 recommended)
• PostgreSQL 15+ and Redis 7+ (provided by compose)

Run the stack

# Clone and enter repo
cd project-arb

# Copy env template — fill secrets locally (never commit .env)
cp env.example .env

# Start all services
docker-compose up -d

# Service Console (topology + secrets)
open http://localhost:8020

# API Gateway
open http://localhost:8004/docs

First admin user (production)

Production has no hardcoded users. Bootstrap once:

curl -X POST http://localhost:8001/auth/setup \
  -H "Content-Type: application/json" \
  -d '{"setup_token": "<SETUP_TOKEN>", "username": "admin", "password": "<strong-password>"}'

See docs/FIRST_USER_SETUP.md.

Run tests

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
pytest tests/ -v

CI runs the full suite on Python 3.11 and 3.14 with Postgres and Redis.

---

Project Layout

project-arb/
├── sag/                    # Core application
│   ├── core/               # Auth, audit, policy, security primitives
│   ├── models/             # Pydantic domain models
│   ├── services/           # One FastAPI app per microservice
│   └── config/             # Settings (env-driven)
├── console/                # Service Console (static UI + secrets API)
├── tests/                  # Unit, integration, security, compliance
├── docs/                   # Runbooks, requirements, security guides
├── gitops/                 # Helm charts, ArgoCD app-of-apps
├── k8s/                    # Kubernetes manifests
├── Dockerfile.*            # Per-service container builds
├── docker-compose.yml      # Local dev stack
└── .github/workflows/      # CI (test, lint, scan) + release

---

Security Highlights

Control	Implementation
CORS	ALLOWED_ORIGINS env — no wildcard * in production
Rate limiting	Fail-secure — deny when Redis unavailable
Secrets	No hardcoded keys; Vault / K8s secrets in prod
Headers	SecurityHeadersMiddleware (CSP, HSTS optional)
Errors	Sanitized 5xx in production
Containers	no-new-privileges, read-only root, tmpfs (prod compose)
CI	gitleaks, pip-audit, bandit, black, flake8

Known issues & fixes: .memory/cards.md

---

Documentation Index

Document	Purpose
ARCHITECTURE.md	System design, diagrams, data model
ADR.md	Architecture decision records
arch.md	Original architecture draft (superseded by ARCHITECTURE.md)
PROJECT_SUMMARY.md	Stack & rules reference
journal.md	Development history & session log
ENDPOINTS_INVENTORY.md	All API endpoints
docs/operational-runbook.md	Production operations
docs/SECRETS_MANAGEMENT.md	Secret storage patterns
docs/SECURITY_TESTING.md	Security test cadence

---

Development Rules

1. REST only — services integrate endpoint-to-endpoint; no shared in-process coupling
2. Independent deploy — each service has its own Dockerfile and CI matrix entry
3. Plan before code — new modules need a reviewed requirement block
4. No hardcoded secrets — use env, Vault, or K8s secrets
5. Track issues — update .memory/cards.md when resolving bugs

---

License

MIT — see project metadata in pyproject.toml.