SentinelForge

Open-source attack-surface discovery, security posture analysis and threat intelligence for modern infrastructure.

What is SentinelForge?

SentinelForge is a defensive security intelligence platform that helps organizations discover and analyze their own attack surfaces. It performs safe, passive reconnaissance against authorized targets and produces structured findings, risk scores, and professional security reports.

Key capabilities:

Asset Discovery — Root domains, subdomains, DNS records, certificates
DNS Analysis — SPF, DMARC, DKIM, CAA, DNSSEC checks
TLS Analysis — Certificate validity, chain issues, protocol versions, cipher suites
HTTP Security — HSTS, CSP, X-Content-Type-Options, Referrer-Policy, cookie flags
Technology Detection — Frameworks, CMS, servers, CDN, analytics fingerprinting
Risk Scoring — Transparent, documented methodology with severity-weighted composites
Threat Intelligence — IP reputation, ASN info, passive DNS enrichment
Security Reports — JSON and PDF export with executive summaries
Web Dashboard — Real-time security posture visualization
CLI — Full command-line access to all scanning capabilities
REST API — OpenAPI-documented endpoints for integration

Defensive Security Scope

SentinelForge is designed exclusively for defensive security assessments of infrastructure you own or have explicit authorization to test.

Users must confirm authorization before every scan
Private IPs, localhost, and metadata endpoints are blocked
SSRF protections prevent scanning unauthorized targets
The platform is not an unrestricted internet scanner
See SECURITY.md for the full security model

Features

Feature	Description
Scan Pipeline	Modular scanner orchestration with 5 specialized modules
Real-time Dashboard	Security score, findings, assets, and risk trends
Findings Management	Severity, category, evidence, remediation for each finding
Risk Engine	Documented scoring: Critical=10, High=8, Medium=5, Low=2, Info=0
CLI Tool	`sentinelforge scan`, `check`, `report`, `assets`, `dashboard`
REST API	Full CRUD with JWT authentication and OpenAPI docs
Threat Intel	Demo provider + CIRCL passive DNS enrichment
Report Generation	JSON export with executive summary, scope, findings, and recommendations

Architecture

graph TD
    A[Frontend - Next.js] --> B[FastAPI Backend]
    B --> C[Scan Orchestrator]
    C --> D1[DNS Scanner]
    C --> D2[Certificate Scanner]
    C --> D3[HTTP Security Scanner]
    C --> D4[Technology Scanner]
    C --> D5[Threat Intel Scanner]
    D1 --> E[Risk Engine]
    D2 --> E
    D3 --> E
    D4 --> E
    D5 --> E
    E --> F[Database - SQLite/PostgreSQL]
    B --> G[Threat Intel Provider]
    G --> H[Demo Provider]
    G --> I[CIRCL Passive DNS]

Components:

Component	Technology	Purpose
Frontend	Next.js 14, TypeScript, Tailwind CSS	Web dashboard and UI
Backend	FastAPI, Python 3.11+	API server and scan orchestration
Database	SQLite (demo) / PostgreSQL (production)	Persistent storage
CLI	Click, Rich	Terminal interface
Scanner	5 modules (DNS, TLS, HTTP, Tech, Threat Intel)	Security analysis
Risk Engine	Weighted composite scoring	Risk quantification

Requirements

Python 3.11+
Node.js 18+
npm (comes with Node)

Optional (for production):

PostgreSQL 14+
Redis 7+
Docker and Docker Compose

Quick Start

The fastest way to get SentinelForge running locally:

# Clone the repository
git clone https://github.com/jakobxtb/SentinelForge.git
cd SentinelForge

# Backend setup
python3.11 -m venv venv
source venv/bin/activate
pip install -e ".[dev]"

# Start the backend (uses SQLite in demo mode)
APP_ENV=development \
DATABASE_URL="sqlite+aiosqlite:///sentinelforge_demo.db" \
APP_SECRET_KEY=dev-secret \
JWT_SECRET_KEY=dev-jwt-secret \
CORS_ORIGINS='["http://localhost:3000"]' \
THREAT_INTEL_DEMO_MODE=true \
uvicorn sentinelforge.main:app --host 0.0.0.0 --port 8000

# In a second terminal — Frontend
cd frontend
npm install
NEXT_PUBLIC_API_URL=http://localhost:3000 npm run dev

Then open:

Dashboard: http://localhost:3000
API Docs: http://localhost:8000/api/docs

Default demo credentials:

Username: demo
Password: demo1234

Docker Quick Start

# Copy environment file
cp .env.example .env

# Build and start all services
docker compose up --build

# Access:
# Dashboard: http://localhost:3000
# API: http://localhost:8000/api/docs

Local Development

Backend

cd sentinelforge/
source venv/bin/activate

# Start with SQLite (demo mode)
APP_ENV=development \
DATABASE_URL="sqlite+aiosqlite:///sentinelforge_demo.db" \
APP_SECRET_KEY=dev-secret \
JWT_SECRET_KEY=dev-jwt-secret \
CORS_ORIGINS='["http://localhost:3000"]' \
uvicorn sentinelforge.main:app --reload --host 0.0.0.0 --port 8000

The backend automatically:

Creates database tables on startup
Seeds a demo user (demo / demo1234)
Registers all 5 scanner modules
Enables rate limiting and security headers

Frontend

cd frontend/
npm install
npm run dev

The frontend proxies API calls to http://localhost:8000 via Next.js rewrites configured in next.config.js.

Workers

In development mode, scans execute synchronously in the API process. For production, the worker system (sentinelforge/workers/) supports async job processing via Redis + arq. To start a worker:

# Requires Redis running
arq sentinelforge.workers.run_scan_job

Web Interface

URL: http://localhost:3000

Page	Path	Description
Dashboard	`/dashboard`	Security score, finding distribution, recent scans
Scans	`/scans`	Scan history, create new scans
Findings	`/findings`	All findings with severity/category filters
Assets	`/assets`	Discovered asset inventory
Threat Intel	`/threat-intel`	Intelligence providers and data sources
Reports	`/reports`	Report generation and export
Settings	`/settings`	Scanner config, security settings, risk scoring

All pages show loading states, error states, and empty states when data is unavailable.

API

Base URL: http://localhost:8000/api/v1

OpenAPI Documentation: http://localhost:8000/api/docs

Authentication

# Register
curl -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "user@test.com", "username": "testuser", "password": "password123"}'

# Login
curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "testuser", "password": "password123"}'

# Use token in subsequent requests
curl http://localhost:8000/api/v1/dashboard \
  -H "Authorization: Bearer <token>"

Key Endpoints

Method	Path	Description
`GET`	`/health`	Health check
`POST`	`/api/v1/auth/register`	Register user
`POST`	`/api/v1/auth/login`	Get JWT token
`GET`	`/api/v1/auth/me`	Current user profile
`POST`	`/api/v1/targets`	Create scan target
`GET`	`/api/v1/targets`	List targets
`POST`	`/api/v1/scans`	Start scan
`GET`	`/api/v1/scans`	List scans
`GET`	`/api/v1/scans/{id}`	Scan details with findings
`DELETE`	`/api/v1/scans/{id}`	Delete scan
`GET`	`/api/v1/findings`	List findings (filterable)
`PATCH`	`/api/v1/findings/{id}`	Update finding
`GET`	`/api/v1/assets`	List discovered assets
`GET`	`/api/v1/risk-scores/{scan_id}`	Risk score details
`GET`	`/api/v1/dashboard`	Dashboard statistics
`POST`	`/api/v1/reports`	Generate report

Health Check

curl http://localhost:8000/health
# {"status": "healthy", "version": "0.1.0"}

CLI

SentinelForge includes a full CLI for terminal-based scanning.

sentinelforge --help
sentinelforge --version

Commands

`sentinelforge login`

Authenticate with the SentinelForge API.

sentinelforge login
# Prompts for username and password
# Stores JWT token in ~/.sentinelforge_token

`sentinelforge scan <domain>`

Scan a domain for security issues.

sentinelforge scan example.com
sentinelforge scan example.com -m dns,certificate

Arguments:

domain — Target domain to scan (required)
-m, --modules — Comma-separated scanner modules (optional, runs all if omitted)

Safety: Prompts for authorization confirmation before scanning.

`sentinelforge assets <domain>`

List discovered assets for a domain.

sentinelforge assets example.com

`sentinelforge report <scan-id>`

Generate a security report for a completed scan.

sentinelforge report <scan-id>
sentinelforge report <scan-id> -f pdf

`sentinelforge check <type> <domain>`

Run a specific security check against a domain.

sentinelforge check tls example.com
sentinelforge check dns example.com
sentinelforge check http example.com
sentinelforge check all example.com

`sentinelforge list-scans`

List all recent scans.

sentinelforge list-scans

`sentinelforge dashboard`

Show dashboard summary in the terminal.

sentinelforge dashboard

Scanner Architecture

SentinelForge uses a modular scanner framework. Each scanner module implements the BaseScanner abstract class:

class BaseScanner(ABC):
    @property
    def module_type(self) -> ScannerModule: ...

    async def validate_target(self, target: str) -> bool: ...

    async def scan(self, target: str, progress_callback=None) -> tuple[list[Finding], list[Asset]]: ...

The ScannerOrchestrator manages module registration, execution, progress tracking, and result aggregation. Each module runs with a 5-minute timeout.

Adding a Custom Scanner

Create a new module in sentinelforge/scanner/modules/
Extend BaseScanner and implement all abstract methods
Register it in sentinelforge/scanner/modules/__init__.py
Add it to the orchestrator in sentinelforge/api/routes.py

DNS Analysis

The DNS scanner performs passive analysis:

Record Enumeration — A, AAAA, MX, NS, TXT, CNAME, SOA, CAA records
SPF Check — Detects missing SPF, soft-fail, open relay (+all)
DMARC Check — Detects missing DMARC, weak policies (p=none)
DKIM Check — Probes common selectors (default, google, selector1, etc.)
CAA Check — Detects Certificate Authority Authorization records
DNSSEC Check — Tests for DNSSEC validation support
TXT Analysis — Flags potentially sensitive data in public TXT records
MX Redundancy — Checks for insufficient MX record redundancy

TLS Analysis

The certificate scanner analyzes TLS configuration:

Certificate Expiration — Critical (expired), warning (7/30/90 days)
Hostname Mismatch — SAN and wildcard verification
Self-signed Detection — Identifies untrusted certificates
Key Strength — Weak cipher detection (RC4, DES, 3DES, NULL)
Protocol Versions — Tests for deprecated SSLv3, TLSv1, TLSv1.1
Cipher Suites — Identifies weak cipher negotiation

HTTP Security

The HTTP scanner checks security headers and configuration:

Headers checked:

Strict-Transport-Security (HSTS) — max-age, includeSubDomains, preload
Content-Security-Policy (CSP) — presence and policy
X-Content-Type-Options — nosniff enforcement
X-Frame-Options — clickjacking protection
Referrer-Policy — referrer leakage prevention
Permissions-Policy — feature restriction
X-XSS-Protection — deprecated XSS auditor detection

Other checks:

HTTP-to-HTTPS redirect enforcement
Cookie security flags (Secure, HttpOnly, SameSite)
Server header technology exposure
X-Powered-By header leakage
Redirect chain security

Threat Intelligence

SentinelForge uses a provider abstraction for threat intelligence enrichment:

Built-in Providers

Provider	Type	Status
Demo Provider	Sample data	Always available (offline)
CIRCL Passive DNS	Free API	Optional (requires network)

Usage

In demo mode (default), the system provides sample threat intelligence data. For real enrichment, configure CIRCL access:

THREAT_INTEL_DEMO_MODE=false

The ThreatIntelProvider interface makes it straightforward to add new providers.

Risk Engine

SentinelForge uses a transparent, documented risk-scoring methodology:

Severity Weights

Severity	Weight
Critical	10.0
High	8.0
Medium	5.0
Low	2.0
Info	0.0

Category Weights

Category	Weight
TLS	1.2
DNS	1.0
HTTP	1.0
Technology	0.8
Threat Intel	1.3
Scanner Error	0.0

Score Components

Finding Risk (50%) — Weighted sum of finding severity × category, log-normalized
Configuration Risk (30%) — TLS/HTTP/DNS finding severity sum
Asset Risk (20%) — Asset count and diversity exposure

Overall Score

Overall = Finding Risk × 0.50 + Configuration Risk × 0.30 + Asset Risk × 0.20

Score Interpretation

Range	Label	Meaning
0-20	Excellent	Strong security posture
20-40	Good	Minor improvements needed
40-60	Moderate	Action recommended
60-80	High Risk	Immediate attention needed
80-100	Critical	Urgent remediation required

This is a transparent scoring methodology, not an industry-certified standard.

Security Model

SentinelForge implements multiple layers of security:

Target Validation

Domain format validation (RFC-compliant regex)
Blocked hostnames: localhost, 127.0.0.1, 0.0.0.0, metadata.google.internal, 169.254.169.254
Private IP blocking: RFC 1918 (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), link-local (169.254.0.0/16), loopback (127.0.0.0/8), IPv6 loopback/ULA/link-local
DNS resolution validation (resolved IPs checked against blocked networks)

SSRF Protection

All HTTP requests validate target URLs against blocked networks
Redirect URLs are sanitized to prevent open redirects
Subprocess arguments are validated to prevent injection

Authentication & Authorization

JWT-based authentication with bcrypt password hashing
Per-user target and scan ownership
Authorization confirmation required before every scan
Audit logging for all security-relevant actions

Rate Limiting

In-memory per-IP rate limiting (default: 100 requests/minute)

Security Headers

X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 0
Referrer-Policy: strict-origin-when-cross-origin
Permissions-Policy: camera=(), microphone=(), geolocation=()
HSTS (production mode)

Timeouts

5-minute timeout per scanner module
15-second HTTP request timeout
10-second DNS resolver timeout

Configuration

Environment Variables

Variable	Default	Description
`APP_ENV`	`development`	Environment (development/staging/production/testing)
`APP_DEBUG`	`false`	Enable debug logging
`APP_SECRET_KEY`	—	Application secret (change in production!)
`APP_HOST`	`0.0.0.0`	Server bind address
`APP_PORT`	`8000`	Server port
`DATABASE_URL`	`sqlite+aiosqlite:///sentinelforge.db`	Database connection string
`REDIS_URL`	`redis://localhost:6379/0`	Redis URL (optional)
`JWT_SECRET_KEY`	—	JWT signing secret (change in production!)
`JWT_ALGORITHM`	`HS256`	JWT algorithm
`JWT_EXPIRATION_MINUTES`	`1440`	Token expiration (24h default)
`CORS_ORIGINS`	`["http://localhost:3000"]`	Allowed CORS origins
`SCAN_TIMEOUT_SECONDS`	`300`	Scanner module timeout
`SCAN_MAX_CONCURRENT`	`5`	Max concurrent scans
`RATE_LIMIT_REQUESTS`	`100`	Requests per window
`RATE_LIMIT_WINDOW_SECONDS`	`60`	Rate limit window
`THREAT_INTEL_ENABLED`	`true`	Enable threat intel
`THREAT_INTEL_DEMO_MODE`	`true`	Use demo provider only
`LOG_LEVEL`	`INFO`	Log level
`LOG_FORMAT`	`json`	Log format (json/console)

.env.example

See .env.example for a complete template with example values.

Testing

Run All Tests

cd sentinelforge/
source venv/bin/activate

# Run all tests
APP_ENV=testing \
DATABASE_URL="sqlite+aiosqlite:///:memory:" \
APP_SECRET_KEY=test-secret \
JWT_SECRET_KEY=test-jwt-secret \
CORS_ORIGINS='["http://localhost:3000"]' \
pytest tests/ -v

Test Categories

Category	Tests	What's Tested
Security	29	SSRF, target validation, IP blocking, URL safety, subprocess safety
Risk Engine	11	Scoring, severity distribution, weight verification
Scanner	9	Orchestration, module registration, error handling
API	21	Auth, targets, scans, findings, dashboard, registration
Threat Intel	7	Provider lookup, aggregation
Total	77

Frontend Build

cd frontend/
npm install
npm run build

Docker

Start

cp .env.example .env
docker compose up --build

Stop

docker compose down

Logs

docker compose logs backend
docker compose logs frontend
docker compose logs -f  # Follow all

Rebuild

docker compose up --build --force-recreate

Reset (Delete Data)

docker compose down -v

Services

Service	Port	Description
`postgres`	5432	PostgreSQL database
`redis`	6379	Redis cache/queue
`backend`	8000	FastAPI server
`frontend`	3000	Next.js dashboard

Troubleshooting

Port already in use

# Find process on port 8000
lsof -i :8000
# Kill it
kill <PID>

Database errors

# For SQLite demo mode, just delete the DB file
rm sentinelforge_demo.db

# The app recreates it on startup

Frontend can't connect to API

Verify backend is running on port 8000: curl http://localhost:8000/health
Check CORS_ORIGINS includes http://localhost:3000
Check NEXT_PUBLIC_API_URL is set to http://localhost:3000 (frontend proxies via Next.js rewrites)

Python version

SentinelForge requires Python 3.11+. Check your version:

python3 --version
# If 3.11+ not available:
python3.11 -m venv venv  # Use specific version

npm install hangs

# Clear cache
rm -rf node_modules package-lock.json
npm install

Project Structure

sentinelforge/
├── sentinelforge/              # Python package
│   ├── api/                    # FastAPI routes, auth, schemas
│   ├── config/                 # Pydantic settings
│   ├── database/               # SQLAlchemy models and connection
│   ├── risk_engine/            # Risk scoring engine
│   ├── scanner/                # Scanner framework
│   │   └── modules/            # DNS, TLS, HTTP, Tech, Threat Intel
│   ├── shared/                 # Security utilities, SSRF protection
│   ├── threat_intelligence/    # Threat intel providers
│   ├── workers/                # Async job workers
│   ├── cli.py                  # CLI entry point
│   └── main.py                 # FastAPI application
├── frontend/                   # Next.js application
│   └── src/
│       ├── app/                # Page routes (dashboard, scans, etc.)
│       ├── components/         # UI components and charts
│       └── lib/                # API client, utilities
├── tests/                      # Pytest test suite
│   └── unit/                   # Unit and integration tests
├── docker/                     # Dockerfiles
├── docs/                       # Documentation
├── .github/                    # CI/CD workflows
├── docker-compose.yml          # Docker Compose config
├── pyproject.toml              # Python project config
├── README.md                   # This file
├── SECURITY.md                 # Security model
├── CONTRIBUTING.md             # Contributing guide
├── CODE_OF_CONDUCT.md          # Code of conduct
├── CHANGELOG.md                # Release history
└── .env.example                # Environment template

Contributing

See CONTRIBUTING.md for guidelines on:

Setting up the development environment
Running tests before submitting PRs
Code style and architecture guidelines
Adding new scanner modules

Security

See SECURITY.md for:

Responsible disclosure policy
Security architecture overview
Threat model
Deployment recommendations

If you discover a security vulnerability, please report it privately via GitHub Security Advisories.

License

SentinelForge is released under the MIT License.

Responsible Use

SentinelForge is a defensive security tool designed for:

Scanning infrastructure you own
Assessing systems you have explicit authorization to test
Security audits of your own domains and applications

Do not use SentinelForge to:

Scan systems without authorization
Perform offensive security testing
Discover vulnerabilities in third-party infrastructure
Conduct reconnaissance for malicious purposes

The platform includes built-in safeguards (authorization confirmation, target validation, SSRF protection) to prevent misuse. Unauthorized scanning is illegal in most jurisdictions.

Name		Name	Last commit message	Last commit date
.github		.github
docker		docker
docs		docs
frontend		frontend
sentinelforge		sentinelforge
tests		tests
.editorconfig		.editorconfig
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
FINAL_REPORT.md		FINAL_REPORT.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
docker-compose.yml		docker-compose.yml
pyproject.toml		pyproject.toml

Latest commit

History

Folders and files

Repository files navigation