GETTING STARTED GUIDE

Get Protected in 5 Minutes.

One command scans your codebase, scores its security health, and turns on real-time protection against risky AI agent actions. No config files, no license key, no dashboard to set up.

Terminal

  
Get Started Free Jump to Install
1. Install 2. Your Score 3. Fix Issues 4. Shield 5. Crucible FAQ
Step 1

Install — one command, that’s it.

There’s nothing to configure and nothing to install permanently. npx downloads and runs Thuban for this session only.

npx thuban protect Click to copy

What it does

Runs the Scanner across every file in your project, activates Shield — all 5 defence layers (File Guard, Shadow Realm, Watchers, Execution Gate, Audit & Recovery) — and runs Crucible to verify your defences actually catch known attack patterns. All in one pass.

💻

Requirements

Node.js 16+ on Windows, macOS, or Linux. No account, no API key, no license key needed to run the free tier.

How long it takes

Most projects finish in 1–3 seconds. Larger monorepos may take a little longer on the first run.

Step 2

Understand your trust score.

Every scan ends with a letter grade — a fast, honest read on how exposed your codebase is right now.

Health score:      B+ (78/100)
Files scanned:     234
Issues found:      23
  Critical:        0
  High:            4
  Warning:         12
  Info:            7
Auto-fixable:      17
A

Excellent. Almost everything auto-fixable is fixed. This is the target state.

B+

Healthy baseline. Normal for most active projects. A few things worth tightening.

C

Needs attention. Real, fixable risk is sitting in the codebase. Run the fixer.

D / F

High exposure. Critical or high-severity findings likely present. Fix before shipping.

Findings are grouped by severity — Critical (exploitable now), High (serious risk), Warning (should fix), Info (best-practice suggestions).

Step 3

Fix issues.

Findings are printed with enough context to act on immediately — no digging through a dashboard required.

[HIGH] Hardcoded API key detected
  src/config/api.js:14
  Rule: secrets.hardcoded-credential
  Fix: move to an environment variable [auto-fixable]

Reading a finding

Each line gives you the severity, a plain-English description, the exact file and line number, which rule triggered it, and a suggested fix. If it says [auto-fixable], Thuban can resolve it for you.

🔧

Auto-fix what you can

Run the fixer to clear every auto-fixable issue in one pass. Nothing destructive happens without a snapshot you can roll back.

npx thuban fix . --fix Click to copy
Secrets & credentialsHardcoded API keys, tokens, passwords committed to source.
Injection risksUnsanitized input reaching shell commands, SQL, or eval.
Unsafe file operationsOverwrites or deletes outside the expected project scope.
Dependency riskKnown-vulnerable or unpinned packages.
Step 4

Shield — protection while you code.

A scan tells you where you stand. Shield watches everything your AI agent does while it's running — every file write, every command. Start it at the beginning of your coding session. When you're done coding, Shield's done watching.

Shield active — monitoring mode. Watching every file write and command in real time.
👁

What it watches

Every file create, edit, and delete, plus every shell command an AI coding agent attempts — before it executes, not after.

🚨

What alerts look like

A terminal warning naming the exact file or command, why it was flagged, and whether it was blocked or just logged for review.

Rollback

If something risky slips through, restore the last protected snapshot instantly:

npx thuban shield rollback Click to copy

See all 5 layers of Shield →

Step 5

Crucible — prove your defences.

Scanning tells you what Thuban thinks it would catch. Crucible proves it — by firing hundreds of real attack patterns at your setup and confirming each one is actually detected.

Running Crucible defence verification...
  515 attack-pattern seeds, 3 intensity levels
✓ Crucible verified: 28/28 defences confirmed
  Detection rate: 99.2%
npx thuban crucible Click to copy
🧪

What it does

Runs a corpus of known attack patterns — credential exfiltration, injection, destructive commands — against your Scanner and Shield rules to confirm each one is actually caught, not just theoretically covered.

📄

The proof report

A pass/fail count per scenario, an overall detection rate, and a shareable summary you can hand to a security reviewer, auditor, or investor as evidence — not just a claim.

See the full Crucible corpus →

FAQ

Common questions

Does my code leave my machine?+
No — 100% local. Scanning, Shield monitoring, and Crucible verification all run on your machine. Your source code is never uploaded anywhere.
Do I need a license key?+
No — just run the command. npx thuban protect works immediately with no account, API key, or license key for the free tier.
What AI tools does it work with?+
Claude Code, Codex, Cursor, Gemini CLI, and any other AI coding agent. Thuban is agent-independent — it protects the filesystem and execution layer, not any single tool.
What does Shield actually do?+
Monitors file writes and commands in real time. It watches every file an AI agent creates or edits and every command it tries to run, alerting you the moment something looks risky.
Is it free?+
Yes — the free tier is unlimited npx thuban protect. Pro is $9/mo and adds Shield's continuous monitoring plus advanced features.
How is this different from a linter?+
Thuban watches what AI agents do, not just what code looks like. A linter checks static code style and patterns; Shield gates real file writes and command execution as they happen.

Ready to get protected?

No install, no config files, no signup required to scan.

Get Started Free
Thuban Help
Ask a question or pick a topic below.