awslabs / awslabs/loom

Produce security governance compliance report

Open
#35 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
Python
Stars
183
Forks
41
Avg merge
8h 6m
Merged PRs (30d)
2

Description

## Overview

Platform engineering teams evaluating Loom for adoption need visibility into the security and governance controls that the system automatically enforces. Add a compliance report — generated from the system's actual configuration, not static documentation — that enumerates all built-in controls across authentication, authorization, infrastructure, data protection, resource governance, and audit, so teams can verify Loom's security posture without manual inspection.

## Context

### Current State
- Loom implements a layered security model spanning Cognito authentication, scope-based RBAC, least-privilege IAM roles, resource tagging policies, Secrets Manager integration, network segmentation, and audit logging, but there is no consolidated, exportable view of these controls.
- `require_scopes()` (`backend/app/dependencies/auth.py:337`) is the existing per-endpoint scope-enforcement mechanism; a new report endpoint should follow the same pattern, gated on a `security:read` scope, consistent with existing `security:read`-gated endpoints in `backend/app/routers/security.py` (e.g. `list_cognito_pools`, `get_role`, `get_authorizer`, `list_credentials`).
- `get_current_user()` (`backend/app/dependencies/auth.py:223`) resolves `LOOM_COGNITO_USER_POOL_ID` and derives group/scope membership; the report's authentication section should describe this resolution without exposing client IDs or secrets, matching the existing auth-config exposure policy (pool ID and region only).

### Key Files
- `backend/app/dependencies/auth.py` — `require_scopes`, `UserInfo`, `get_current_user`, group-to-scope mappings
- `backend/app/routers/security.py` — security admin endpoints (roles, authorizers, credentials, permissions); add the new report endpoint here
- `backend/app/routers/settings.py` — tag policy and tag profile CRUD
- `backend/app/routers/admin.py` — audit endpoints (login, action, pageview, sessions, summary)
- `backend/app/services/iam.py` — IAM role creation and management
- `backend/app/routers/credentials.py` — credential management with Secrets Manager
- `shared/iac/role.yaml` — least-privilege IAM role template
- `shared/iac/cognito.yaml` — Cognito User Pool, groups, scopes, clients
- `shared/iac/infra.yaml` — ALB, security groups, TLS, network configuration
- `SPECIFICATIONS.md` — root security considerations and auth architecture

### Technology Stack
- **Backend**: Python, FastAPI, SQLAlchemy
- **Frontend**: TypeScript, React, Vite, shadcn/ui, Tailwind CSS
- **Infra**: AWS SAM / CloudFormation (`shared/iac/`), Cognito, IAM, Secrets Manager, ALB

### References
- Source issue: [heeki/loom#68](https://github.com/heeki/loom/issues/68) — original requirements draft for this report

## Requirements

### R1: report-endpoint
Expose `GET /api/security/compliance-report` in `backend/app/routers/security.py` (scope: `security:read`, via `require_scopes("security:read")`) that generates a structured compliance report enumerating all security and governance controls the system implements. Return the report as JSON with one section per control domain (R2–R8, R10 below).

### R2: authentication-controls
Document authentication controls: Cognito User Pool configuration (password policy, MFA status), OAuth2 flows (`USER_PASSWORD_AUTH` for users, `client_credentials` for M2M), token validation and propagation, and the auth-config endpoint exposure policy (pool ID and region only — never client IDs or secrets).

### R3: authorization-controls
Document authorization controls: the resource server scopes defined in `shared/iac/cognito.yaml`, group-to-scope mappings for all Cognito groups (admin and user types), per-endpoint scope enforcement via `require_scopes`, and user-type/group-based resource filtering (e.g. demo users see only `loom:group=demo` resources).

### R4: iam-controls
Document IAM controls: the least-privilege role template (`shared/iac/role.yaml`) with its specific policy statements (bedrock, bedrock-agentcore, secretsmanager, observability, memory), conditional policy inclusion (memory policy only when a memory ARN is provided), and the managed role lifecycle (creation, attachment, deletion) as implemented in `backend/app/services/iam.py`.

### R5: data-protection-controls
Document data protection controls: Secrets Manager usage for credential storage (client secrets, OAuth2 tokens) with in-memory caching (5-minute TTL), write-only secret fields (never returned in GET responses), secret cleanup on resource deletion, and the `has_oauth2_secret` boolean pattern for indicating secret presence without exposure.

### R6: resource-governance-controls
Document resource governance controls: tag policy enforcement (required vs. optional tags, default values, validation on deploy) and tag profiles (named presets satisfying required policies) as implemented in `backend/app/routers/settings.py`, tag propagation to all AWS resources created during deployment, and group-based resource scoping.

### R7: network-controls
Document network controls: ALB with TLS termination, HTTP-to-HTTPS redirect, security group configurations (ALB ingress, ECS task ingress restricted to ALB), private subnet placement for ECS tasks, and SSM-based database access (no direct RDS exposure) — sourced from `shared/iac/infra.yaml`.

### R8: audit-controls
Document audit controls: login event tracking with browser session correlation, action audit trail (category, type, resource name), page view tracking with duration, per-session timeline reconstruction, and admin dashboard analytics, as implemented in `backend/app/routers/admin.py`.

### R9: frontend-report-page
Provide a "Compliance Report" view accessible to users with `security:read` scope. Render the report sections in a readable format with expandable control domains and support exporting the report as JSON.

### R10: deployment-controls
Document deployment controls: SAM CLI-based deployments with parameterized templates, environment-based naming conventions, infrastructure-as-code for all resources (no manual console changes), and the multi-stack separation under `shared/iac/` for blast-radius containment.

## Testing

- Run backend tests: `cd backend && make test`
- Run frontend typecheck: `cd frontend && npx tsc --noEmit`
- Verify `GET /api/security/compliance-report` returns `403` without `security:read` scope and a well-formed JSON report with it
- Verify no secrets, client IDs, or credentials appear anywhere in the report payload
- Verify the report's IAM, tag policy, and network sections reflect the actual deployed configuration (not hardcoded values) by comparing against `shared/iac/role.yaml`, tag policy settings, and `shared/iac/infra.yaml`
- Verify the frontend Compliance Report page renders all sections and the JSON export matches the API response

## Out of Scope

- Automated remediation of compliance gaps (this issue only covers reporting)
- Continuous/scheduled compliance scanning or alerting
- Third-party compliance framework mapping (e.g. SOC 2, ISO 27001 control IDs) — the report documents Loom's actual controls, not external framework crosswalks
- Historical/point-in-time compliance snapshots or diffing between report runs

Contributor guide

Open the contributing guide

Research direction

Start with backend/app/routers/security.py and backend/app/dependencies/auth.py, then trace the referenced settings, admin, credentials, IAM, and shared/iac files to identify configuration-backed controls. Run the backend tests and frontend typecheck before examining the API and frontend entry points. Done means the scoped endpoint and Compliance Report view cover the required sections, reflect deployed configuration, pass the listed authorization and safety checks, and export matching JSON without secrets.

Written by the indexing model from the issue text.

Assessment

Tech stack
aws, fastapi, python, react, sqlalchemy, tailwindcss, typescript, vite
Domain
api, authentication, authorization, backend, cloud, devops, documentation, frontend, infrastructure, observability, security
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.