Skip to content

About

No description, website, or topics provided.

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

73 Commits

Folders and files

Repository files navigation

CryptoScope

CI

A cryptographic inventory and quantum-risk dashboard. CryptoScope scans TLS endpoints, records every algorithm, key, certificate and protocol it finds, scores the risk (including exposure to future quantum computers), analyses TLS traffic at scale, and shows it all live on a dashboard. A crypto-agility module demonstrates how to move from RSA/ECDSA to the post-quantum ML-DSA signature standard by changing configuration, not code.

Built as a portfolio project, in the spirit of crypto-inventory tools such as ISARA Advance, with NestJS, Next.js, PostgreSQL, Elasticsearch, BullMQ and Socket.IO.

CryptoScope overview: KPI tiles, key-algorithm and weak-handshake charts

What it does

Discover A TLS scanner reads the protocol, cipher, key exchange, certificate key and signature algorithm of any host, and detects hybrid post-quantum key exchange (X25519MLKEM768).
Assess A rules engine turns each scan into findings (expired certs, weak RSA, SHA-1, TLS 1.0, quantum-vulnerable keys, no PQ key exchange) and a 0–100 risk score.
Inventory PostgreSQL keeps assets, the full scan history, deduplicated certificates and findings: 350k+ rows of seed data, with indexed queries.
Analyse traffic Elasticsearch aggregates 500k TLS handshake logs: key algorithms, weak handshakes per hour, hosts with RSA < 2048, % quantum-vulnerable traffic.
Scale Scans run as BullMQ jobs with retries and backoff; progress streams to the browser over Socket.IO.
Protect JWT auth with admin/viewer roles, scrypt passwords, rate limiting, security headers, SSRF protection.
Migrate A crypto-agility module signs with RSA, ECDSA, ML-DSA-65 or a hybrid ECDSA + ML-DSA, selected by config.

How this relates to quantum-safe security

The threat. A large enough quantum computer running Shor's algorithm breaks RSA and elliptic-curve cryptography, the basis of almost every TLS certificate, code signature and key exchange today. Two consequences:

  • Harvest now, decrypt later: traffic recorded today with classical key exchange (ECDH, RSA) can be decrypted once such a computer exists. Long-lived secrets are already at risk.
  • Forgery later: RSA/ECDSA signatures (certificates, firmware, documents) become forgeable, so trust has to move to new algorithms before that happens.

The response. NIST standardised post-quantum algorithms in 2024: ML-KEM (FIPS 203) for key exchange and ML-DSA (FIPS 204) for signatures, and plans to deprecate RSA/ECC around 2030 and disallow them by 2035 (NIST IR 8547). Migrating a large organisation takes years, and it starts with knowing where the vulnerable cryptography is.

How CryptoScope maps to that migration:

Migration step What CryptoScope does Where
1. Discover: find all cryptography in use Scans endpoints and parses certificates, including ML-DSA certificates Node can't parse itself (a small DER reader) scanner, Step 2
2. Assess: which assets are quantum-vulnerable? QUANTUM_VULNERABLE_KEY for every RSA/ECC key; NO_PQ_KEY_EXCHANGE when hybrid ML-KEM isn't negotiated risk rules
3. Measure exposure: how much traffic is at risk? % of TLS handshakes using classical key exchange (85% in the sample data) analytics, docs
4. Prioritise Risk score and level per asset; current findings; expiring certificates (renewal = migration opportunity) dashboard
5. Become crypto-agile Algorithms behind one interface, chosen by config; signatures name their algorithm so old and new coexist crypto-agility
6. Migrate safely ML-DSA-65 signing for real (Node.js 24), and hybrid ECDSA + ML-DSA that stays secure if either algorithm holds Step 9

What the real-world scans show: google.com and cloudflare.com already negotiate hybrid X25519MLKEM768 key exchange, github.com doesn't, and every certificate scanned still uses a quantum-vulnerable RSA or ECDSA key. That is today's typical picture: key exchange is migrating first (harvest-now-decrypt-later), and signatures are next. And the cost is real: an ML-DSA-65 signature is 3,309 bytes vs 71 for ECDSA, which matters for certificate chains, TLS handshakes and constrained devices.

Architecture

flowchart LR
    user([Browser]) -->|HTTPS + JWT| fe[Next.js dashboard<br/>:3000]
    user -->|REST + JWT| api
    user <-->|Socket.IO /scans| api

    subgraph backend [NestJS backend :3001]
        api[REST API<br/>auth · assets · findings<br/>analytics · crypto]
        worker[BullMQ worker<br/>scan → save → index]
        listener[Queue-events listener]
        scanner[TLS scanner<br/>+ SSRF policy]
        risk[Risk engine]
        crypto[Crypto providers<br/>RSA · ECDSA · ML-DSA · hybrid]
        api --> crypto
        worker --> scanner --> risk
    end

    api -->|enqueue| redis[(Redis<br/>BullMQ · rate limits)]
    redis -->|jobs| worker
    worker -->|progress| redis
    redis -->|events| listener --> api
    scanner -->|TLS handshake| internet((TLS endpoints))
    api --> pg[(PostgreSQL<br/>inventory)]
    worker -->|1 transaction| pg
    worker -->|bulk index| es[(Elasticsearch<br/>findings · handshake logs)]
    api -->|aggregations| es
    kibana[Kibana :5601] --> es
Loading
Path What happens
Start a scan POST /api/scan-jobs → job in Redis → 202 Accepted → the worker scans, applies the risk rules, saves in one Postgres transaction, indexes findings into Elasticsearch. Retries use exponential backoff, and every step is idempotent.
Live progress worker → job.updateProgress() → Redis stream → each API process → Socket.IO → browser. Workers can run in separate containers.
Dashboard data Inventory from PostgreSQL (each asset's latest scan); traffic analytics from Elasticsearch aggregations.

More detail: async pipeline · data model · security.

Quick start

Requirements: Docker (Docker Desktop or Rancher Desktop) with at least 4 GB of memory for its VM. Node.js 22+ is only needed for the seed scripts and local development.

git clone https://github.com/mnahsanofficial/CryptoScope.git && cd CryptoScope
cp .env.example .env

Edit .env and set the three secrets (the app refuses to start without them):

JWT_SECRET=          # openssl rand -base64 48
POSTGRES_PASSWORD=   # anything, local only
ADMIN_PASSWORD=      # 12+ characters; the first admin is ADMIN_EMAIL / ADMIN_PASSWORD

Start everything with one command (the first run downloads images and takes a few minutes):

docker compose up -d --build --wait

Optional: fill it with realistic data (the dashboard is more interesting with it):

cd backend && npm ci
npm run seed            # 20,000 demo assets, 100,000 scans, ~200,000 findings (~20 s)
npm run seed:real       # 144 real public hosts, added and scanned live through the API (~2 min; stack must be running)
npm run findings:reindex  # copy the seeded findings into the Elasticsearch search index (~7 s)
npm run logs:generate   # 500,000 TLS handshake logs into Elasticsearch (~5 s)

The seeded assets are synthetic: their domains are made up (cdn.initech-2410.ca), so they're marked synthetic and tagged Demo in the UI. Scanning one for real can only end in "Host not found", so they can't be selected for scanning, and Rescan real assets on the Overview targets only the riskiest real hosts.

npm run seed:real adds 144 real hosts (list): badssl.com's deliberately broken test servers, PKI and standards bodies (NIST, CISA, ISARA, DigiCert, Let's Encrypt), cloud providers, banks and popular sites. In October 2026, 48% of them negotiated hybrid post-quantum key exchange (X25519MLKEM768), and 100% still served an RSA or ECDSA certificate.

Service URL
Dashboard http://localhost:3000 (sign in with ADMIN_EMAIL / ADMIN_PASSWORD)
API http://localhost:3001/api (health: /api/health, readiness: /api/health/ready)
Kibana http://localhost:5601 (data view "TLS handshakes" is created by logs:generate)
Elasticsearch http://localhost:9200
PostgreSQL / Redis localhost:5434 / localhost:6379
./scripts/check-health.sh   # checks every service
docker compose down         # stop (add -v to delete the data volumes)

Local development (hot reload)

docker compose up -d postgres redis elasticsearch kibana
cd backend && npm run start:dev    # http://localhost:3001/api
cd frontend && npm run dev         # http://localhost:3000

The backend reads the root .env (hosts = localhost); inside Docker, compose overrides them with service names.

Configuration

All settings come from environment variables (.env); see .env.example for the full list. No secrets live in code, and the app validates its configuration at startup.

Variable Default Purpose
JWT_SECRET (required, 32+ chars) Signs access tokens
JWT_EXPIRES_IN 1h Access token lifetime
ADMIN_EMAIL / ADMIN_PASSWORD – First admin, created only when no users exist
POSTGRES_*, REDIS_*, ELASTICSEARCH_NODE see .env.example Connections (Postgres host port 5434)
CRYPTO_SIGNATURE_ALGORITHM ECDSA-P256-SHA256 RSA-PSS-3072-SHA256, ML-DSA-65, HYBRID-ECDSA-P256+ML-DSA-65
SCAN_TIMEOUT_MS / SCAN_CONCURRENCY 5000 / 10 Per-connection timeout, parallel hosts per scan
SCAN_WORKER_CONCURRENCY / SCAN_JOB_ATTEMPTS / SCAN_RETRY_DELAY_MS 5 / 3 / 2000 Queue worker, retries, backoff
SCAN_ALLOW_PRIVATE_TARGETS false SSRF protection; true only for local testing
RATE_LIMIT / RATE_LIMIT_TTL_MS 100 / 60000 Requests per IP per window (login: 5/min)
TRUST_PROXY_HOPS 0 Set behind a load balancer so rate limits use the real client IP

API

All endpoints except login and health need Authorization: Bearer <token>. 🔒 = admin only (viewers get 403). Get a token:

curl -s -X POST localhost:3001/api/auth/login -H 'content-type: application/json' \
  -d '{"email":"admin@cryptoscope.local","password":"<ADMIN_PASSWORD>"}'

Auth and users

Method Path Description
POST /api/auth/login { email, password } → { accessToken, tokenType, user }. Public; 5 attempts/min
GET /api/auth/me The current user
POST / GET /api/users 🔒 Create ({ email, password, role }) / list users

Inventory and scanning

Method Path Description
GET / POST /api/assets List (search also accepts URLs or host:port, riskLevel, environment, synthetic, sort, order, page, pageSize) / 🔒 create { host, port, label, environment, scanNow }: queues the first scan unless scanNow: false
GET / PATCH / DELETE /api/assets/:id Read / 🔒 update / 🔒 delete (cascades to scans and findings)
POST /api/assets/:id/scans 🔒 Queue a scan → 202 { jobId, scanId, created }
POST /api/scan-jobs 🔒 Queue a batch { assetIds } → 202 { batchId, total, jobs }
GET /api/scan-jobs, /api/scan-jobs/:jobId, /api/scan-jobs/batches/:batchId Queue counts, one job, batch progress
GET /api/assets/:id/scans, /api/scans/:id Scan history; one scan with certificate and findings
GET /api/findings Filters severity, category, ruleId, assetId, from, to, latestOnly; sort createdAt or severity; paginated
GET /api/findings/search Elasticsearch full-text search: q (typo-tolerant, prefix, host + text) plus severity, category, ruleId, currentOnly; ranked, highlighted, with severity/category counts
GET /api/certificates/expiring Certificates in use expiring within days (default 30), most urgent first
GET /api/dashboard/overview Totals, average risk, current findings, % quantum-vulnerable, expiring certificates
POST /api/scanner/scan 🔒 Ad-hoc scan of up to 50 targets, with risk assessments (not stored)
GET /api/scanner/seed-targets, /api/risk/rules Demo targets; risk rules and weights

TLS traffic analytics (Elasticsearch): all accept from and to (ISO 8601, default: last 7 days)

Method Path Description
GET /api/analytics/handshakes/key-algorithms Count by key algorithm (terms) with key sizes
GET /api/analytics/handshakes/weak-per-interval Weak handshakes per interval (date_histogram + filter), by reason
GET /api/analytics/handshakes/top-weak-rsa-hosts Top limit hosts still using RSA < 2048
GET /api/analytics/handshakes/quantum-vulnerable % of traffic with quantum-vulnerable key exchange, by group
GET /api/analytics/handshakes/search Full-text q (query context) + tlsVersion, host filters (filter context)

Crypto-agility

Method Path Description
GET /api/crypto/providers Algorithms: family, quantum-safe, available, active, measured sizes and speed
POST /api/crypto/sign 🔒 { message, algorithm? } → { algorithm, keyId, signature, publicKey, quantumSafe }
POST /api/crypto/verify { message, algorithm, signature, keyId | publicKey } → { valid }

Health: GET /api/health (liveness) and GET /api/health/ready (readiness: Postgres, Redis, Elasticsearch) are public.

Live events: Socket.IO namespace /scans (io(url + "/scans", { auth: { token } })) emits scan.progress and batch.progress.

Screenshots

Overview Live scan progress
Overview: KPI tiles, key-algorithm and weak-handshake charts, with a note where the traffic data stops Batch scan of three hosts: "Scanning 3" in the navbar, "Scanning…" on each row, per-job progress pushed over Socket.IO
Assets (admin) Findings search (Elasticsearch)
Assets: add-asset form, search, filters, and the inventory sorted by risk Typo-tolerant search "globex certifcate expird": highlighted matches and a count on each severity chip
Phone Sign in
Findings on a 375 px phone: host and date move under the finding, no sideways scrolling Sign-in page

UI and UX. One set of design tokens drives light and dark mode, and every page works at phone width (no horizontal page scroll). On phones, secondary table columns fold into the main cell. Severity is always a glyph plus a label, never color alone. Empty results explain why and offer a fix ("1 match is hidden by the severity filter → Show all severities"). Icon-only navigation keeps accessible names, and each page has its own browser title. Details: docs/dashboard.md.

Data model

erDiagram
    assets ||--o{ scans : "has history of"
    certificates ||--o{ scans : "seen in"
    scans ||--o{ findings : produces
    assets ||--o{ findings : "denormalised link"
    assets |o--o| scans : "latest_scan_id"

    assets {
        uuid id PK
        varchar host "unique with port"
        int port
        smallint latest_risk_score "copy of latest scan"
        uuid latest_scan_id FK
    }
    scans {
        uuid id PK
        uuid asset_id FK "ON DELETE CASCADE"
        uuid certificate_id FK "ON DELETE SET NULL"
        scan_status status
        varchar protocol
        boolean post_quantum_key_exchange
        smallint risk_score
    }
    certificates {
        uuid id PK
        varchar fingerprint_sha256 "unique"
        timestamptz valid_to
        varchar key_algorithm
        varchar signature_algorithm
    }
    findings {
        uuid id PK
        uuid scan_id FK
        uuid asset_id FK
        finding_severity severity
        varchar rule_id
        jsonb evidence
    }
    users {
        uuid id PK
        varchar email "unique"
        varchar password_hash "scrypt"
        user_role role
    }
Loading

Certificates are stored once per fingerprint; every scan is kept as history; latest_* columns are deliberate denormalised copies for fast dashboards. Schema changes are hand-written migrations, checked against the entities. One slow query and its fix (an index, 214x faster, EXPLAIN ANALYZE before/after) is documented in docs/query-optimization.md.

Testing

Suite Command Count Covers
Backend unit cd backend && npm test 242 Scanner (real local TLS servers), DER parser, every risk rule, mappers, query builders, worker retry policy, scrypt, JWT config, SSRF policy, crypto providers (shared contract tests)
Backend e2e cd backend && npm run test:e2e 64 Real app + Postgres + Redis/BullMQ + Elasticsearch + Socket.IO: CRUD, async scans, retries, analytics with exact counts, auth/roles, an audit of every route, rate limits, sign/verify
Frontend cd frontend && npm test 34 Live-event reducer, API client, session/JWT expiry, chart helpers (ticks, gaps), login form, search highlighting, date/expiry labels, scan failure labels, reload throttling

CI (GitHub Actions, .github/workflows/ci.yml) runs, on every push and PR:

  • backend type-check, unit tests and build on Node 22 and 24 (on 24 the real ML-DSA tests run too);
  • frontend lint, tests and production build;
  • the e2e suite against real Postgres, Redis and Elasticsearch service containers;
  • npm audit of production dependencies.

Project structure

CryptoScope/
├── backend/                  NestJS API (Node.js 24 in Docker)
│   ├── src/scanner/          TLS scanner, DER certificate parser, SSRF policy
│   ├── src/risk/             risk rules + scoring engine
│   ├── src/assets|scans|findings/   inventory REST API (TypeORM)
│   ├── src/database/         migrations, seed (350k+ rows), EXPLAIN demo
│   ├── src/analytics/        Elasticsearch mapping, log generator, aggregations
│   ├── src/scan-jobs/        BullMQ producer/worker, Socket.IO gateway
│   ├── src/auth|users/       JWT, roles, scrypt
│   ├── src/crypto-agility/   CryptoProvider: RSA, ECDSA, ML-DSA, hybrid
│   └── test/                 e2e suites
├── frontend/                 Next.js 16 dashboard (Tailwind, Recharts, Socket.IO client)
├── docs/                     design notes per topic + screenshots
├── scripts/check-health.sh   smoke test for the whole stack
├── .github/workflows/ci.yml  CI
└── docker-compose.yml        the whole stack: one `docker compose up`

Design documents

Topic Document
Query optimisation (EXPLAIN ANALYZE, composite index) docs/query-optimization.md
Elasticsearch mapping, aggregations, query vs filter context, findings search docs/elasticsearch.md
Async pipeline: retries, idempotency, real-time docs/async-pipeline.md
Security: auth, roles, scrypt, SSRF, secrets, production gaps docs/security.md
Dashboard: data flow, token storage, charts, CSP docs/dashboard.md
Crypto-agility and post-quantum signatures docs/crypto-agility.md

How it was built

Step by step, one reviewed pull request per step:

  1. Project setup: monorepo, docker-compose, health checks
  2. TLS scanner with post-quantum key exchange detection
  3. Rule-based risk scoring
  4. PostgreSQL data model, REST API, 214x query optimisation
  5. Elasticsearch TLS handshake analytics
  6. Async pipeline with BullMQ and Socket.IO
  7. Security: JWT roles, scrypt, rate limiting, SSRF protection
  8. Next.js dashboard
  9. Crypto-agility with ML-DSA and hybrid signatures
  10. Final polish: README, architecture, CI

Limitations

This is a learning and portfolio project, not a production service. Notable gaps (see the honest list in docs/security.md):

  • Elasticsearch, Kibana and Redis run without authentication or TLS (local development only).
  • Signing keys are generated in memory; production needs a KMS/HSM, persistence and rotation.
  • Access tokens only (no refresh tokens or revocation) stored in sessionStorage; a backend-for-frontend with httpOnly cookies would be stronger.
  • Scan targets are TLS endpoints only (no SSH, code signing, or source-code crypto discovery).

About

No description, website, or topics provided.

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages