Thuban

Thuban is an independent AI software assurance platform for pull requests, releases, and codebase trust. It combines codebase intelligence, scanner-driven risk detection, and Forge-style verification so teams can decide whether AI-assisted changes are safe to merge.

Capability boundary: Thuban is an AI-code-specific triage layer. Deprecated API detection, phantom/hallucinated API detection, and AI code-smell detection are a curated set of common patterns frequently generated by AI coding tools — not an exhaustive or dynamically-learned catalog. The exception is named-export verification, which is real AST-based analysis (via @babel/parser, not pattern matching): it checks whether import { foo } from 'bar' actually resolves to a real export of bar. Thuban's taint tracker (packages/scanner/taint-tracker.js) traces user-input sources (req.query/body/params, process.argv/env, sys.argv, request.args, etc.) through variable assignment, concatenation, and template interpolation to dangerous SQL/XSS sinks — for JS/TS this now follows taint across file boundaries too: if file A exports a tainted value (module.exports/export) and file B imports it (require()/import, including destructured imports and re-exports), uses in file B are flagged with crossFile: true and a sourceFile pointing back to the origin. It does not yet track taint through function call/return boundaries within a file, or across Python module imports. Thuban is not a substitute for deep security auditing. For full interprocedural data-flow assurance, pair Thuban with tools like Semgrep or CodeQL.

Product wedge

Thuban is built around a PR assurance wedge:

• connect a GitHub repository through a future GitHub App
• analyze changed files and architectural blast radius
• run assurance checks and evidence collection
• issue a clear verdict with remediation guidance

This standalone extraction is based on the Thuban product strategy and the prior CODEX specifications inside orion-main.

Repository layout

apps/
  api/        Express placeholder API for ingestion, assurance, and attestations
  web/        Next.js placeholder operator UI
packages/
  scanner/    Extracted Sentinel scanner and monitoring substrate
  forge/      Extracted Forge verifier and verification data
docs/
  source/     Original CODEX and Orion intelligence specs
  strategy/   Product strategy and viability docs
  schema/     Thuban-only database schema extract
  venture/    Original venture README source

What is real today

• packages/scanner/ contains extracted working Sentinel code from Orion
• packages/forge/forge-verifier.js contains extracted Forge verification logic
• packages/forge/data/forge-verifications/ contains historical verification artifacts
• docs/ contains the original strategy, viability, and CODEX-era source materials

What is placeholder today

• apps/api/ is an Express starter aligned to the target product shape
• apps/web/ is a minimal Next.js starter for the future assurance dashboard
• Postgres integration, GitHub App auth, webhook ingestion, PR check-runs, and production orchestration are planned but not yet implemented here

See ARCHITECTURE.md for a clear real-vs-placeholder breakdown.

Architecture overview

Apps

• apps/api: future control plane and integration surface for repos, pull requests, audits, policies, and attestations
• apps/web: future UI for onboarding repos, reviewing audit evidence, and tracking trust history

Packages

• packages/scanner: repository scanning, dependency graphing, drift detection, health checks, alerting, and secret/credential exposure scanning for hardcoded API keys, passwords, secrets in source code, .env files not gitignored, database connection strings with passwords, private keys, high-entropy strings, and secrets still exposed in git history, and secret/credential exposure scanning for hardcoded API keys, passwords, secrets in source code, .env files not gitignored, database connection strings with passwords, private keys, high-entropy strings, and secrets still exposed in git history
• packages/forge: attestation and verification workflow plus verification history

Data

• Postgres is the intended system of record
• the included schema extract in docs/schema/ORION-ECOSYSTEM-SCHEMA.thuban.json contains only the thuban tables from Orion
• packaged JSON artifacts are historical examples, not the final persistence model

Getting started

Prerequisites

• Node.js 20+
• npm 10+
• Postgres 15+ for future API work

Install

npm install

Run the placeholder apps

npm run dev:api
npm run dev:web

Explore the extracted code

• scanner entrypoint: packages/scanner/index.js
• secret scan utility: quickSecretScan([...files], { rootPath }) or new SecretScanner({ rootPath }).scanAll() with output including file path, line number, secret type, severity, and fix recommendation
• forge verifier: packages/forge/forge-verifier.js
• product strategy: docs/strategy/THUBAN-PRODUCT-STRATEGY.md
• architecture notes: ARCHITECTURE.md

Thuban Pro recurring scans

Thuban Pro adds scheduled recurring scans for local repositories with change detection, local history, and notification stubs.

What it does

• stores monitor configuration per repo in ~/.thuban/monitor/config.json
• runs the existing scanner pipeline on a schedule
• saves each run as JSON history in ~/.thuban/monitor/runs/<repo-id>/
• compares each run to the previous run to surface:
  • new issues
  • resolved issues
  • issue-count trend
  • hallucination / secret / tech-debt metric deltas
• writes notification records to ~/.thuban/monitor/notifications.json
• gates monitor/history/trend commands to Pro and above

Commands

npx thuban monitor . --once
npx thuban monitor . --frequency daily
npx thuban monitor . --frequency weekly
npx thuban monitor . --frequency custom --interval-ms 3600000
npx thuban history .
npx thuban trend .

Notification channels

Current implementation supports:

• inbox — local notification inbox persisted to disk
• console — console alert via the existing alert manager
• email — stubbed for future delivery integration
• webhook — stubbed for future delivery integration

Example:

npx thuban monitor . --once --notify inbox,console

How scheduling works

• daily = every 24 hours
• weekly = every 7 days
• custom = any interval via --interval-ms
• npx thuban monitor . starts a foreground daemon-like process until stopped
• npx thuban monitor . --once performs one scheduled-style run immediately and stores history

Diff detection

Each issue is fingerprinted from file, category, id, line, and message. Thuban compares the latest run against the previous run and records:

• added: issues not seen in the previous run
• resolved: issues that disappeared
• metricsDelta: changes in issue count, hallucinations, secrets, and tech debt metrics

This makes recurring scans useful for “what changed since yesterday?” rather than just “scan again.”

Website deployment

The public site at https://thuban.dev is deployed from the repository root docs/ folder via GitHub Pages.

• workflow: .github/workflows/deploy-website.yml
• trigger: pushes to main that change docs/**, or manual workflow_dispatch
• deploy artifact: the docs/ directory uploaded directly to GitHub Pages
• custom domain: docs/CNAME

Important deployment notes:

• apps/web/ is a placeholder Next.js app and is not part of the live GitHub Pages deployment
• there is currently no build/export pipeline from apps/web/ into docs/
• updating apps/web/ alone will not change thuban.dev
• to update the live site, edit the static files in docs/ or add a future export step that writes static output into docs/

Current practical workflow:

1. make website content changes in docs/
2. commit and push to main
3. GitHub Actions runs Deploy Website to GitHub Pages
4. GitHub Pages publishes the uploaded docs/ artifact to https://thuban.dev

Planned next steps

1. implement GitHub App installation and webhook ingestion
2. persist repos, analyses, issues, and fixes in Postgres
3. convert Sentinel and Forge flows into API-driven services
4. connect PR check-runs and release attestation exports
5. build the dashboard for audit runs, verdicts, and trust history