Volver a la documentacióndocs/architecture/overview.mdRepositorio privado

Architecture overview / Visión general de la arquitectura

Centinela is four planes separated by services, identities, networks and credentials. The only link between the decision plane and the execution plane is one SQS queue carrying signed plans with signed approval attestations. The process that talks to the LLM never holds write credentials.

C4 — context

flowchart LR
  subgraph External["External, untrusted sources"]
    Feeds["CVE List V5 · NVD · KEV · EPSS · OSV · GHSA · distro feeds · CSAF/VEX"]
    Clouds["AWS Organizations · GCP Org · EKS/GKE · ECR/Artifact Registry"]
    GitHub["GitHub (Reader App, read-only)"]
  end
  Users["Analysts · Service owners · Security leads · Auditors (SSO + WebAuthn)"]
  Chat["Slack / Teams / Email / Jira — links only"]
  Centinela["Centinela"]
  GitHubW["GitHub (Executor App: contents + PRs write)"]
  Feeds --> Centinela
  Clouds --> Centinela
  GitHub --> Centinela
  Users <--> Centinela
  Centinela --> Chat
  Centinela -- "pull requests only" --> GitHubW

C4 — containers (planes)

flowchart TB
  subgraph Ingest["INGESTION PLANE — read only"]
    FI[feed-ingestor] --> VN[vuln-normalizer] --> VDB[(vuln DB)]
    IC[inventory-collectors aws/gcp/k8s/registries] --> AG[(asset graph · Postgres RLS)]
    RS[repo-scanner · ephemeral sandbox] --> AG
  end
  subgraph Analysis["ANALYSIS PLANE — no write credentials"]
    M[matcher · deterministic] --> R[risk-engine · explainable]
    R --> A[analysis-agent · Claude via Bedrock VPC endpoint]
    A --> PV[plan-validator] --> PS[plan-signer · KMS Sign]
  end
  subgraph Decision["DECISION PLANE"]
    AS[approval-service] --- OPA[policy-engine · OPA]
    UI[web console · SSO + WebAuthn step-up]
    N[notifier · links only]
  end
  subgraph Exec["EXECUTION PLANE — isolated account/namespace"]
    EX[executor · Go · verifies plan + attestation signatures, re-evaluates policy, freshness]
  end
  VDB --> M
  AG --> M
  PS -- "signed plan" --> AS
  AS -- "plan + signed attestations (SQS, single producer)" --> EX
  EX -- "PR / ticket / runbook" --> GH[GitHub]
  Ingest & Analysis & Decision & Exec --> AUD[(audit log · hash chain · S3 Object Lock)]

Trust boundaries

Boundary	Enforced by
External content → system	`Untrusted` type (core), delimited prompt blocks, injection detector, deterministic post-LLM validation
Analysis → Decision	plan `content_hash` + ECDSA signature (KMS `plan-signer`, Sign only by plan-signer role)
Decision → Execution	`ApprovalAttestation` signed by `approval-service` key, bound to the plan hash; SQS queue policy: only approval-service sends, only executor receives; analysis roles carry an explicit Deny
Execution → World	GitHub Executor App (contents + pull_requests write only), Network Firewall allowlist, NetworkPolicy, tainted node pool / separate account
Tenant ↔ tenant	Postgres RLS forced per session, per-tenant KMS CMK, per-tenant ExternalId
Everyone → Audit	append-only table (no UPDATE/DELETE grants + trigger), hash chain, Object Lock COMPLIANCE

Data flows (happy path)

Feed connector polls (cursor/ETag) → raw record stored → normalizer merges aliases into one Vulnerability → vulnerability.upserted.
Matcher evaluates against the graph (and inversely on inventory change) → canonical Findings with evidence and paths → risk engine scores them with policy-versioned weights → findings.ready.
Analysis agent (read-only tools) writes narrative + PlanDraft from the closed action catalog → validator → plan-signer → plan.ready.
approval-service verifies the signature, computes approver requirements with OPA, notifies (links only). Approver passes WebAuthn step-up, opens the diff, decides → signed attestation(s) → when requirements are met, plan.approved is enqueued.
Executor verifies everything again (signatures, hash, expiry, SoD, two-person, kill switch, policy bundle hash, freshness) → opens a PR idempotently → tracks CI/merge/ArgoCD → matcher verifies closure.

See data-model.md, message-contracts.md, observability.md.

ES: Cuatro planos separados por servicios, identidades, redes y credenciales. La única unión entre decisión y ejecución es una cola SQS con planes firmados y atestaciones de aprobación firmadas. El proceso que habla con el LLM nunca tiene credenciales de escritura.