OpenWatch - Open Source SCAP Compliance Scanner

OpenWatch is an open-source SCAP (Security Content Automation Protocol) compliance scanner for automated security assessments. Scan your infrastructure against STIG, CIS, and custom security profiles.

Quick Start

Prerequisites

• Docker or Podman
• Linux system (RHEL/Ubuntu recommended)
• 4GB RAM, 2 CPU cores minimum

Installation

# Clone and start
git clone https://github.com/hanalyx/openwatch.git
cd openwatch
./start-openwatch.sh --runtime docker --build

# Wait 60-90 seconds for services to start
# Access web interface at http://localhost:3000
# Default credentials: admin / admin

Important: Change the default admin password immediately after first login.

First Scan

1. Add SSH credentials (Settings → System Credentials)

   • Name: default-ssh
   • Username: Your SSH user
   • Authentication: Password or SSH key

2. Add a host (Hosts → Add Host)

   • Hostname/IP: Your target system
   • SSH Port: 22 (default)
   • Credentials: Select default-ssh

3. Upload SCAP content (Content → Upload)

   • Download SCAP content from NIST NCP
   • Upload the .xml data-stream file

4. Run a scan (Scanning → New Scan)

   • Select host and SCAP profile
   • Click "Start Scan"
   • View results in real-time

Architecture

┌─────────────┬─────────────┬─────────────┐
│  Frontend   │   Backend   │   Scanner   │
│   (React)   │  (FastAPI)  │  (OpenSCAP) │
└──────┬──────┴──────┬──────┴──────┬──────┘
       │             │             │
   ┌───▼───┬────────▼────────┬────▼────┐
   │ NGINX │   PostgreSQL    │  Redis  │
   └───────┴─────────────────┴─────────┘

Components:

• Frontend: React with Material Design 3
• Backend: FastAPI with OpenSCAP integration
• Database: PostgreSQL for compliance data
• Task Queue: Celery with Redis
• Web Server: NGINX with TLS

Features

• Multi-host scanning: Scan 100+ hosts in parallel
• STIG/CIS profiles: Pre-configured security baselines
• Real-time results: Live scan progress and results
• SSH authentication: Password and key-based auth
• Container deployment: Docker/Podman ready
• REST API: Full automation support

Configuration

Environment Variables

Create backend/.env with required settings:

# Generate secure keys
SECRET_KEY=$(openssl rand -hex 32)
MASTER_KEY=$(openssl rand -hex 32)

# Database connection
DATABASE_URL=postgresql://openwatch:password@db:5432/openwatch

# Optional settings
OPENWATCH_DEBUG=false
OPENWATCH_REQUIRE_HTTPS=true

See backend/.env.example for complete configuration options.

Container Runtime

Docker:

./start-openwatch.sh --runtime docker
./stop-openwatch.sh                # Safe stop (preserves data)

Podman (rootless):

./start-openwatch.sh --runtime podman
./stop-openwatch.sh                # Safe stop (preserves data)

⚠️ IMPORTANT: By default, ./stop-openwatch.sh preserves all data. Use OPENWATCH_CLEAN_STOP=true ./stop-openwatch.sh only when you want to delete all data.

Troubleshooting

Services won't start

# Check container logs
docker logs openwatch-backend
docker logs openwatch-frontend

# Restart services (preserves data)
./stop-openwatch.sh
./start-openwatch.sh --runtime docker --build

Data disappeared after restart

# This is caused by running old versions of stop-openwatch.sh
# Update to latest version (safe by default):
git pull origin main

# Data is lost and must be re-entered
# Future restarts will preserve data

Database connection errors

# Verify database is running
docker-compose ps

# Check database logs
docker-compose logs db

Scan failures

• Verify SSH credentials are correct
• Ensure target host is reachable
• Check target host has oscap installed (for remote scans)
• Review scan logs in Scanning → Scan History

See docs/FIRST_RUN_SETUP.md for detailed troubleshooting.

Development

Backend Development

cd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Set environment variables
export SECRET_KEY="your-secret-key"
export MASTER_KEY="your-master-key"

# Start backend
uvicorn app.main:app --reload --port 8000

Frontend Development

cd frontend
npm install
npm run dev  # Runs on port 3001

Running Tests

# Backend tests
cd backend
pip install pytest pytest-asyncio pytest-cov
pytest tests/ -v

# Frontend tests
cd frontend
npm test

Important: Always run tests before committing. See docs/STOP_BREAKING_THINGS.md for testing strategy.

Security

• Encryption: AES-256-GCM for credentials, TLS for transport
• Authentication: JWT with RS256 signing, Argon2id password hashing
• FIPS compliance: FIPS 140-2 Level 1 cryptography
• Audit logging: All security events logged
• MFA Support: TOTP with SHA-256 backup codes

Security Audits

OpenWatch undergoes regular security audits. Latest audit reports:

• Security Audit Report - Comprehensive cryptographic and dependency analysis
• Security Findings Summary - Executive summary with remediation steps

Report vulnerabilities: security@hanalyx.com

License

OpenWatch Community License (AGPLv3 + Managed Service Exception)

OpenWatch is licensed under the GNU Affero General Public License v3.0 with a Managed Service Exception. This means:

• ✅ Free to use for internal business purposes
• ✅ Free to modify and distribute (with source code)
• ✅ Self-hosted deployment permitted
• ❌ Cannot offer as SaaS to third parties without commercial license

Commercial licensing available for managed service providers and SaaS offerings.

For details, see LICENSE or contact legal@hanalyx.com

Acknowledgments

Built with:

• OpenSCAP - SCAP scanning engine
• FastAPI - Python web framework
• React - Frontend framework
• Material-UI - UI components
• Podman - Container runtime