> ## Documentation Index
> Fetch the complete documentation index at: https://docs.genesiscomputing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Security Posture Summary

> Genesis security audit procedures and posture overview

# Genesis Security Audit Procedures

**Prepared for:** Chief Security Officer
**Date:** March 15, 2026
**Repository:** `genesis-computing-ai/genesis-agents` (private)

***

## Executive Summary

Genesis maintains a layered security scanning pipeline that operates at three levels: source code analysis (ruff security and correctness rules), container image vulnerability scanning of built images (which also covers Python and Node.js dependency CVEs), and continuous monitoring of published Docker images. All scans run automatically in CI/CD via GitHub Actions; depending on the check, failures block PR merges and/or GA release promotion. Failures trigger Slack notifications and automated triage agents that analyze root causes and propose fixes.

***

## Security Controls Overview

| Layer | Tool | What It Checks | Gating Type | Frequency |
| - | - | - | - | - |
| **Source code** | Ruff (S, PLE rules) | Security anti-patterns, insecure function usage, hardcoded secrets in code | Blocks merge | Every PR + every push to main |
| **Container image (build)** | Trivy (Aqua Security) | HIGH/CRITICAL CVEs in the Docker image built from source (Python + Node.js libraries) | Blocks merge; Blocks GA release | PRs touching Docker/dependency files + release branch pushes + on-demand |
| **Container image (published)** | Trivy (Aqua Security) | HIGH/CRITICAL CVEs in published GHCR images (edge, rc, GA) | Blocks GA release | Every 2 hours + after every RC build |
| **Accepted risks** | `unsuppress.py` (Trivy, PyPI, Go module proxy) | Whether each suppressed CVE is still impossible to fix, by re-deriving what holds the fix back and scanning new upstream releases | Opens a pull request; red until it is decided | Every 2 hours |
| **Secrets in commits** | GitGuardian | Leaked credentials, API keys, tokens in committed code | Blocks merge | Every PR |
| **Code review** | CodeRabbit (AI) | Security issues, bugs, correctness problems flagged during PR review | Advisory | Every PR |
| **Dependency updates** | GitHub Dependabot | Alerts for known vulnerabilities in declared dependencies | Advisory | Continuous |

***

## Detailed Procedure: Container Image Vulnerability Scanning (Build-Time)

**Workflow:** `Check: Docker Build` (`build-docker-test.yml`)
**Scanner:** Trivy (Aqua Security), via composite action `.github/actions/trivy-scan/`

### When It Runs

| Trigger | Condition |
| - | - |
| **Pull request** | When changes touch: `container/**`, `Dockerfile*`, `pyproject.toml`, `uv.lock`, `package.json`, `yarn.lock`, or the workflow file itself |
| **Release branch push** | Every push to `release-*` branches (gates RC builds) |
| **On-demand** | Manual trigger via `workflow_dispatch` |

### What It Does

1. Builds the full Docker image (base + app layers) from current source
2. Runs a container health check (server must report ready within 180s)
3. **Scans the built image with Trivy** for HIGH and CRITICAL library vulnerabilities
4. Fails the workflow (exit code 1) if any vulnerability is found
5. On failure, posts to the `#engineering-check-engine` Slack channel and dispatches the triage agent

### Scan Configuration

| Parameter | Value | Rationale |
| - | - | - |
| `severity` | `CRITICAL,HIGH` | Focus on actionable vulnerabilities; MEDIUM/LOW excluded to reduce noise |
| `vuln-type` | `library` | Scans Python (pip) and Node.js (npm) libraries only; OS-level packages excluded as they are not exploitable in our container context |
| `scanners` | `vulnerability` | Vulnerability matching only; secret scanning handled separately by GitGuardian |
| `exit-code` | `1` | Hard-fail on any finding |

### Why Library-Only Scanning

During evaluation, unfiltered scanning reported \~51 HIGH/CRITICAL CVEs, of which \~37 were OS-level (linux kernel headers, system Python packages, glibc, gnupg). These packages are:

* Not directly invocable by application code
* Present as build dependencies, not runtime attack surface
* Managed by the base image's OS vendor, not by us

Filtering to `library` reduces findings to only actionable application dependency vulnerabilities — the packages we directly control and can upgrade.

### Scanner Selection Rationale

We evaluated three open-source scanners (Trivy, Grype, Docker Scout) against a commercial reference vulnerability report containing 21 HIGH/CRITICAL CVEs:

| Scanner | Detection Rate | Extra Findings (noise) | Selection |
| - | - | - | - |
| Trivy | 12/17 applicable CVEs (71%) | 49 (32 kernel, 17 other) | **Selected** |
| Grype | 13/17 (76%) | 76 (57 Chrome, 11 Go, 5 Node) | Not selected |
| Docker Scout | Could not test (requires paid login) | — | Not selected |

Trivy was selected over Grype despite marginally lower detection rate because:

* 3x larger community (32K vs 11.5K GitHub stars) — better support ecosystem
* All-in-one scanning (vulns + IaC + secrets + licenses) if we expand scope later
* Official GitHub Action with 7-minute setup in CI
* Every CVE Trivy missed, Grype also missed (shared blind spot in transitive dependency attribution)

***

## Detailed Procedure: Published Image Security Monitoring

**Workflow:** `Check: Image Security` (`check-image-security.yml`)
**Trigger:** `Trigger: Security Scans` (`trigger-security-scans.yml`)
**Scanner:** Trivy (Aqua Security), via composite action `.github/actions/trivy-scan/`

### Purpose

New CVE advisories are published several times a day across the Python and Node.js ecosystems, and advisories relevant to packages in our dependency tree appear several times a week. A vulnerability may have no known CVE when the image is built but be disclosed hours later.

While build-time scanning catches vulnerabilities at the point of code change, published image monitoring continuously re-scans the images already deployed in production (GA), staging (RC), and development (edge) to catch these newly disclosed CVEs promptly.

### When It Runs

| Trigger | Scope | Image Tag |
| - | - | - |
| **Scheduled (every 2 hours)** | main, latest RC branch, latest GA tag | `edge`, `rc`, `v{X.Y.Z}` |
| **After every RC build** | The release branch that produced the RC | `rc` |
| **On-demand** | Any branch or custom image ref | Configurable |

The scheduled trigger (`trigger-security-scans.yml`, cron `30 */2 * * *`) automatically resolves the latest release branch and GA tag, then dispatches three independent `check-image-security.yml` runs — one per scope. The RC build workflow (`release-create-rc.yml`) additionally dispatches a security scan immediately after the Docker image is published to GHCR.

### What It Does

1. Resolves the correct GHCR image reference for the target scope
2. Verifies the image exists in GHCR (gracefully skips if not yet published)
3. **Scans the published image with Trivy** for HIGH and CRITICAL vulnerabilities
4. On failure, posts to the `#engineering-check-engine` Slack channel and dispatches the triage agent

### Scan Scopes

| Scope | Image Tag | What It Represents |
| - | - | - |
| **main** | `edge` | Latest build from the `main` branch — development bleeding edge |
| **RC** | `rc` | Latest release candidate image — deployed to Railway staging |
| **GA** | `v{X.Y.Z}` (e.g. `v1.12.1`) | Current generally-available release — deployed to production |

### Dashboard Integration

The release dashboard reads this workflow's run history to display per-scope **\[SEC]** indicator lights, showing at a glance whether each scope's published image is clean.

***

## Detailed Procedure: Source Code Lint Audit

**Workflow:** `Check: Lint` (`check-lint.yml`)
**Runs on:** Every pull request to `main` + every push to `main`

### What It Does

This workflow runs ruff with Bandit security (S-series) and Pylint error (PLE-series) rules on all source code in `genesis_bots/` and enforces a **ratchet policy** — the number of issues can only go down, never up. Any increase fails the CI.

| Check | Tool | Scope | Failure Criteria |
| - | - | - | - |
| Code security & correctness | `ruff --select=S,PLE` | All source code in `genesis_bots/` | More violations than the previous audit baseline |

Dependency vulnerability scanning (pip-audit, npm-audit) was previously part of a separate `security-audit.yml` workflow but has been removed. Dependency CVEs are now caught by the Trivy container image scans, which detect vulnerable Python and Node.js libraries in the built Docker image.

### Ratchet Mechanism

Results are recorded in `security_audit/audit.csv` after each run on `main`. Each subsequent run compares against this baseline. A PR that introduces even one new security or correctness violation is blocked. Reductions are always accepted.

### Accepted Risk Process

When a ruff finding is a false positive, a `# noqa: S###` comment (with justification) is added to the flagged line. For container image CVEs whose fix cannot be installed, a `.trivyignore` entry records why carrying the vulnerability is acceptable, with a ticket.

An accepted risk does not stay accepted by default. Every two hours, the `review-ignore-file` job in the Main `Check: Image Security` run re-derives, for each suppressed CVE, what holds the fix back: the parent package whose requirements refuse the fixed version, or the compiled binary the vulnerable library sits inside. It reads the newest release of each from the package registry, scans a newly released binary with Trivy, and opens a pull request when the fix has become installable or the suppression no longer suppresses anything. While such a pull request waits for a decision the run fails, which turns the security light on the release dashboard red until it is merged or declined. Its report states, per CVE, exactly why we are not fixing it yet. The procedure is documented in `docs/security/MANAGING_TRIVY_IGNORE.md`.

### Code Security Rules

The code audit enforces 78 Bandit-derived security rules (S-series) covering: hardcoded credentials, insecure crypto, SQL injection, shell injection, XML vulnerabilities, insecure SSL/TLS, and more. It also enforces 30+ Pylint error rules (PLE-series) for critical code correctness issues. Full rule listing is maintained in `security_audit/security-audit.md`.

***

## Failure Notifications and Automated Triage

### Slack Notifications

When any check-engine workflow fails, a structured notification is posted to the `#engineering-check-engine` Slack channel via the reusable `reusable-check-engine-failure.yml` workflow. The notification includes the check name, branch, commit, failure summary, and a direct link to the failed run.

The following checks currently have failure notifications wired:

| Check | Workflow | Notification |
| - | - | - |
| Docker Build + Trivy | `build-docker-test.yml` | Yes |
| Published Image Security | `check-image-security.yml` | Yes |
| Release Branch Sync | `check-sync.yml` | Yes |
| iOS Harness | `test-ios-harness.yml` | Yes |

### Automated Triage Agent

On failure, check-engine workflows dispatch a **Triage Agent** (`triage-agent.yml`) that autonomously analyzes the failure and, when possible, proposes a fix:

1. **Fetches failed job logs** from the GitHub Actions run
2. **Classifies** the failure as infrastructure (transient) or code (actionable)
3. **Checks for existing triage work** to avoid duplicate fix attempts
4. **Proposes a fix PR** when the failure is code-caused — targeting the correct branch, respecting release-branch sync rules (cherry-pick to preserve `git patch-id`)
5. **Monitors CI on the fix PR** until all checks pass
6. **Reports back** to the Slack thread with classification, root cause, confidence level, and fix PR link

The triage agent uses variant-specific prompts (e.g., `triage-security.md` for Trivy failures) that provide domain-specific fix strategies — such as bumping dependency versions, regenerating lock files, or adding `.trivyignore` entries for unfixable CVEs.

***

## Detailed Procedure: Secrets Detection

**Service:** GitGuardian
**Runs on:** Every pull request (external integration, not a GitHub Actions workflow)

GitGuardian scans every commit in every PR for leaked secrets including API keys, tokens, passwords, private keys, and cloud credentials. It runs as a GitHub check and blocks merge on detection.

***

## Detailed Procedure: Automated Code Review

**Service:** CodeRabbit (AI-powered)
**Runs on:** Every pull request

CodeRabbit performs automated code review on every PR, flagging potential security issues, bugs, and correctness problems. Its findings are advisory (do not block merge) but are triaged and addressed by the engineering team before merge.

***

## Dependency Update Monitoring

**Service:** GitHub Dependabot
**Coverage:** Alerts enabled for known vulnerabilities in declared dependencies

Dependabot monitors the repository's dependency manifests and raises alerts when new vulnerabilities are disclosed. It also proposes automated PRs to upgrade vulnerable packages. As of this writing, Dependabot reports 25 known advisories against the default branch (15 high, 9 moderate, 1 low) — these are primarily OS-level packages excluded from the container scan scope and transitive dependencies with no direct fix available.

***

## GitHub Actions Security Hardening

The repository enforces a **selected actions allow list** at the repository level. Only explicitly approved third-party actions may be used in any workflow:

| Approved Action | Purpose |
| - | - |
| `docker/*` | Docker image build and registry operations |
| `astral-sh/setup-uv` | Python package manager |
| `azure/setup-helm` | Helm chart operations |
| `softprops/action-gh-release` | GitHub release automation |
| `aws-actions/*` | AWS EKS/ECR deployments |
| `aquasecurity/trivy-action` | Container vulnerability scanning |
| `aquasecurity/setup-trivy` | Trivy binary installation |

All GitHub-owned actions (`actions/*`) are automatically permitted. Verified marketplace actions are **not** automatically permitted — they must be explicitly added.

This prevents supply-chain attacks via compromised or malicious third-party actions.