https://github.com/writer/aperio
Open-source SSPM for SIEM-native teams: detect SaaS posture risks, inventory OAuth shadow IT, and stream normalized findings to your security stack.
https://github.com/writer/aperio
cloud-security cybersecurity identity-security mcp multi-tenant oauth oauth-security posture-management saas saas-security security-automation security-monitoring security-posture-management shadow-it siem sspm
Last synced: 19 days ago
JSON representation
Open-source SSPM for SIEM-native teams: detect SaaS posture risks, inventory OAuth shadow IT, and stream normalized findings to your security stack.
- Host: GitHub
- URL: https://github.com/writer/aperio
- Owner: writer
- License: mit
- Created: 2026-06-05T18:34:05.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-06-22T14:51:58.000Z (about 1 month ago)
- Last Synced: 2026-06-22T16:27:32.951Z (about 1 month ago)
- Topics: cloud-security, cybersecurity, identity-security, mcp, multi-tenant, oauth, oauth-security, posture-management, saas, saas-security, security-automation, security-monitoring, security-posture-management, shadow-it, siem, sspm
- Language: Go
- Size: 2.88 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 29
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Aperio
**SaaS Detection & Response on top of Cerebro.**
Aperio is an open-source SaaS Detection & Response platform. It connects to your SaaS estate, fires Cerebro-grounded SaaS detections, opens human-owned incidents with a replayable timeline, runs human-gated response actions with separation of duties, and forwards every lifecycle event to the SIEM you already operate. The current `main` branch ships a Go/ConnectRPC API backed by Prisma/Postgres data, a Next.js operator console, an stdio MCP broker, an ingestion worker, an optional NATS JetStream event bus, and a durable SIEM dispatcher with adapters for Splunk HEC, Panther, Panopticon, Elasticsearch, Datadog Logs, generic webhooks, and JSON Lines files.
In practical terms, Aperio ingests connector events, evaluates SaaS detection rules, opens and dedupes incidents enriched with Cerebro graph and claim context, gates response actions behind two-person approval, and fans canonical `aperio.finding.v1` envelopes out to your SIEM destinations.
   
---
## Current capabilities
- **Connector catalog** — built-in support for GitHub, Slack, Google Workspace, Okta, 1Password, Microsoft 365, and Atlassian (Jira & Confluence), with encrypted credential storage (AES-256-GCM) and per-check toggles.
- **SaaS detections** — public-repo detection (GitHub), MFA-disabled detection (Slack), and a deep Google Workspace pack covering external sharing, admin posture (super-admin 2SV, recovery emails), Gmail auto-forwarding / delegates / send-as, and the domain-wide-delegation allow-list.
- **Shadow IT** — per-user `users.tokens.list` scan that catalogs every third-party OAuth app users have authorized, with graduated risk scoring (CRITICAL/HIGH/MEDIUM/LOW) calibrated against Google scope sensitivity.
- **Findings lifecycle** — auto-resolution on next sync when the underlying signal disappears, evidence persistence, severity scoring, dedupe by stable key, and risk exceptions with compensating controls.
- **SIEM fanout** — durable outbox with adapters for Splunk HEC, Panther, Panopticon, Elasticsearch, Datadog Logs, generic webhooks, and JSON Lines file sinks. Canonical envelope `aperio.finding.v1`.
- **Event contracts** — protobuf-backed Aperio lifecycle envelopes wrapped in Cerebro-compatible `EventEnvelope` messages, with optional NATS JetStream publishing for ingestion, finding lifecycle, and claim fanout events.
- **Remediation** — real handlers for Okta (suspend, reset MFA) and Slack (revoke OAuth app); the rest are stubbed and pluggable.
- **Operator console** — Next.js app with dashboard, findings, apps, shadow IT, security graph, connectors, SIEM destinations, and admin pages. Full-text command palette, role-aware navigation, MFA enrollment.
- **Agents and MCP** — tenant-scoped agent runtime that creates `AgentProposal` rows requiring human approval before any provider-side write executes. An stdio MCP broker mirrors core task and SIEM actions over JSON-RPC for MCP-native clients.
- **Multi-tenant by default** — every entity is scoped to an `Organization`. Tenant isolation is enforced at the route, repository, and integration layer, with cross-tenant test coverage in `internal/bootstrap/tenant_isolation_test.go`.
---
## Architecture
```
Operator console (Next.js) MCP clients (stdio)
| |
v v
Go/ConnectRPC API MCP broker
(cmd/aperio, internal) (cmd/mcp-broker, internal/mcpbroker)
|
+-----------------------------+
| | |
v v v
Connectors Detection SIEM dispatcher
(GitHub, rules + (outbox worker)
Slack, findings |
Google, lifecycle v
Okta, | Splunk / Panther /
1Pass, v Panopticon / Elastic /
M365, Postgres Datadog / Webhook / JSONL
Atlassian) (state)
|
v
Optional NATS JetStream
(Cerebro-compatible events)
```
The Go API is the single source of truth for connector, finding, admin, auth, and SIEM workflows. The ingestion worker pulls audit-log events into the same Postgres state store. The SIEM dispatcher reads the `SiemDelivery` outbox and ships each finding to every enabled destination with retry/backoff. When `APERIO_EVENT_BUS=nats`, Go and worker processes also publish validated protobuf lifecycle events to JetStream; otherwise publishing is a safe no-op. Credentials are encrypted at rest with AES-256-GCM via `packages/security`.
---
## Quick start
### Prerequisites
- Node.js 20+ (the repo targets the active LTS line).
- Go 1.25+ (for the ConnectRPC API in `cmd/aperio`).
- Docker (for local Postgres and NATS via `docker-compose.yml`) or any reachable Postgres 15+.
- npm 10+ (ships with Node 20).
- GNU Make (preinstalled on macOS and most Linux distros) to use the `make` targets below.
### First run
The fastest path uses the Makefile; run `make help` to see every target.
```bash
git clone https://github.com/writer/Aperio.git
cd Aperio
make setup # .env, deps, Postgres, migrations, and seed data
make dev # Go API on :4100 + Next.js console on :3000
```
`DATABASE_URL` in `.env` is the single source of truth for the local Postgres port: `make` publishes the docker-compose database on the port embedded there and hands the Go server a pgx-compatible DSN automatically (Prisma's `?schema=public` is stripped and `sslmode=disable` is added for local connections).
Prefer to run each step yourself? The manual flow is equivalent:
```bash
git clone https://github.com/writer/Aperio.git
cd Aperio
docker compose up -d # local Postgres on :5432
npm install
cp .env.example .env # fill in local secrets before sharing
npm run db:generate
npx prisma migrate dev --schema packages/db/prisma/schema.prisma
# create your local .env (see Configuration below for the full reference)
cat > .env <