OSCAL Report Generator

Generate Statement of Applicability (SOA), System Security Plans (SSP), and Cloud Control Matrix (CCM) from OSCAL catalogs. React frontend, Node.js backend; AI suggestions via AWS Bedrock or Mistral API.

---

Quick start

# Install dependencies (root, backend, frontend)
npm run install:all

# Run locally: backend (port 3020) + frontend (port 3021)
npm run dev

Open http://localhost:3021. Backend API: http://localhost:3020.

---

Design and configuration

• AI: AWS Bedrock (default) or Mistral API. No self-hosted Ollama. Configure in Settings → AI Integration or via config/app/config.json (see docs/AI_INTEGRATION.md).
• Auth: Session-based; users in config/app/users.json (PBKDF2). Optional OIDC/SSO e.g. Okta (see docs/OIDC_SSO_INTEGRATION.md).
• Database (optional): PostgreSQL or AWS RDS for storing custom/organisational fields. Configure in Settings → Database; export data is synced when enabled (see docs/DATABASE_INTEGRATION.md).
• Branching: Development (default) → Quality → main / Prod. Pre_Prod retired. See docs/GIT_AND_RELEASE.md.
• AWS (Terraform): ALB, Green/Blue EC2 (ASG + EBS), S3 (installer/ app snapshot, config/ & logs/ per role). Resources tagged (Project, Environment, Stack). See terraform/README.md and docs/AWS_OPERATIONS.md.
• EC2 / S3 deploy: Application bits are s3://<logs-bucket>/installer/ (not rsync from the laptop by default). ./scripts/deploy-to-ec2.sh --update-s3 uploads the repo to that prefix (with excludes for .cursor, terraform/, docs/, etc.); ./scripts/deploy-to-ec2.sh, --blue, or --both only pull from S3 on the instances, run dnf upgrade -y or yum update -y first, then install/build/restart. AWS credentials for upload come from Pass (same entry shape as terraform/run-with-aws-pass.sh). Cron on instances: scripts/ec2_automation.sh (S3 backup; optional installer sync / OS updates via ec2_automation.env). Details: docs/DEPLOYMENT.md, docs/AWS_OPERATIONS.md.

---

Directory structure

OSCAL_Reports/
├── backend/                 # Node.js + Express (port 3020)
│   ├── auth/                # Authentication, user management
│   ├── server.js            # Main server
│   ├── configManager.js     # Config (config.json, users.json)
│   ├── mistralService.js    # Mistral/Bedrock AI
│   ├── gemmaService.js      # Gemma (Bedrock/Google AI)
│   ├── controlSuggestionEngine.js
│   └── ...
├── frontend/                # React + Vite (dev port 3021)
│   └── src/
│       ├── components/      # UI (AIIntegration, CatalogChoice, etc.)
│       ├── contexts/
│       └── services/
├── config/
│   └── app/                 # Runtime config (gitignored in practice)
│       ├── config.json.example
│       └── users.json.example
├── scripts/                 # Deploy, EC2 automation, SSH, debug
│   ├── deploy-to-ec2.sh     # S3 installer/ + SSH deploy (Green/Blue; see header in script)
│   ├── ec2_automation.sh    # Cron: S3 backup, optional installer pull / OS updates
│   ├── ssh-ec2.sh           # SSH to Green or Blue via Terraform outputs
│   ├── lib/                 # Shared helpers (e.g. Pass + Terraform paths)
│   └── debug/               # e.g. alb-target-health.sh, EC2 diagnostics
├── terraform/               # AWS (ALB, Green/Blue, S3)
│   ├── envs/                # Per-account (e.g. aws4403)
│   └── ...
├── test_cases/              # Backend tests (Jest)
├── docs/                    # Documentation
├── package.json             # Root scripts (dev, install:all, lint, lint:all, probe-bedrock-gemma)
├── docker-compose.yml       # Single service (no Ollama)
└── Dockerfile

---

Configuration parameters

Source	Purpose
config/app/config.json	AI (Bedrock/Mistral), messaging, SSO. Use examples in config/app/*.example.
config/app/users.json	Users and PBKDF2 hashes. Populated from users.json.example or Settings.
.env (root)	Optional: USERS_PATH, CONFIG_PATH, PORT; backend loads from repo root in development.
Environment	NODE_ENV, PORT, AWS_REGION / AWS credentials for Bedrock when not using IAM role.

See docs/ARCHITECTURE.md and docs/AWS_OPERATIONS.md for full configuration and deployment.

---

Documentation index

Topic	Document
Summary	docs/PROJECT_SUMMARY.md – purpose, stack, layout
Start	docs/README.md – doc index
Deploy	docs/DEPLOYMENT.md
Architecture	docs/ARCHITECTURE.md
AWS / Terraform	docs/AWS_OPERATIONS.md, terraform/README.md
Branching / Git / release	docs/GIT_AND_RELEASE.md
AI (Bedrock/Mistral)	docs/AI_INTEGRATION.md, docs/AWS_OPERATIONS.md
Database (optional)	docs/DATABASE_INTEGRATION.md – PostgreSQL/RDS, export sync, extended_data

---

What's new in 1.7.23

• Dependencies: Dependabot updates merged into Quality — AWS SDK, express-rate-limit 8.x, pdfkit 0.19, pg, React 19.2.7, and related security/toolchain bumps (#45–#61).
• CI / tests: Quality Gates action updates; OIDC and Docker bootstrap unit tests stable in CI; optional live OIDC probe via OSCAL_RUN_OIDC_PROBE=1.
• Deploy: keekar/oscal_reports:v1.7.23 when published to Docker Hub.

Details: docs/CHANGELOG.md.

---

What's new in 1.7.22

• Pass bundle (laptop): All OSCAL app secrets in one pass entry PROD/OSCAL/AWS_SM (same JSON as AWS SM); migrate legacy OSCAL/* with migrate-pass-entries-to-bundle.sh.
• EC2 deploy safety: DEPLOY_CONFIG_S3_SKIP=1 for code-only deploys; golden config/default/ on S3 for restore; no more accidental SSO/config wipe from force S3 sync.
• Generic OIDC / SSO: Fixes orphan _sm pointers when SM empty; login providers API returns Generic SSO when secret is resolvable.
• Deploy: keekar/oscal_reports:v1.7.22 on Docker Hub; EC2 via safe flags above.

Details: docs/CHANGELOG.md.

---

What's new in 1.7.21 (previous)

• Multi-Report Comparison: Export uses the same generate-ssp path as the main app; fixes gateway timeouts, validation modal dismiss, and _ComplianceReport filenames.
• AI suggestions: Per-control prompts (catalog description, statement parts) so Gemma/Mistral outputs vary by control.
• Generic OIDC (Docker/NAS): tlsRelaxed when Authentik TLS chain fails Node verification; EC2 production remains Okta-first.
• Deploy: keekar/oscal_reports:v1.7.21 on Docker Hub; EC2 via ./scripts/deploy-to-ec2.sh --update-s3 then --both.

Details: docs/CHANGELOG.md.

---

License

MIT. See LICENSE.

---

Version: 1.7.23 (see root package.json) · Last updated: June 2026