Security copilot for Stellar Soroban smart contracts — static analysis, formal verification with Z3, on-chain runtime guards, and an auditor-friendly dashboard, all driven by a single SARIF-clean engine.
Note
When an EVM contract ships a bug, the community has a decade of tools — Slither, Mythril, Foundry, Certora — to catch it. Soroban shipped to mainnet in 2024 with almost none of that scaffolding. Every team writes the same review checklist from scratch. Every audit re-discovers the same five footguns.
Sanctifier is the missing layer. One engine, twelve canonical rules, three deployment surfaces. Built specifically for Soroban's authorization model, storage TTL semantics, SEP-41 token interface, and gas/event quirks. Open source. Auditor-grade. Drop-in for CI.
Every finding has a stable code — S001..S012 — so you can filter, suppress, and trend it across releases.
| Code | What it catches | Why it bites |
|---|---|---|
S001 | Missing require_auth on state-changing calls | Anyone can drain your contract |
S002 | panic! / unwrap / expect in contract paths | Locked state, no recovery |
S003 | Unchecked arithmetic — overflow, underflow, truncation | Silent loss-of-funds rounding |
S004 | Ledger entries pushing the size threshold | Refusal at write time, mid-tx |
S005 | Storage-key collisions between data paths | Cross-feature data corruption |
S006 | Unsafe patterns — including timestamp-as-randomness | Predictable winners, exploit replay |
S007 | Your custom YAML rules | Your house style, enforced |
S008 | Inconsistent or missing event emissions | Wallets and indexers go blind |
S009 | Unhandled Result return values | Silent failures masquerading as success |
S010 | Upgrade / admin / governance risk | Single-key takeover paths |
S011 | Z3-disproved invariants | Mathematical guarantees you don't have |
S012 | SEP-41 token interface deviations | Wallets reject your token |
The community vulnerability database matches known CVE-style patterns (SOL-2024-*) against your AST — so a published exploit anywhere becomes a finding everywhere.
If your contract verifies ZK proofs on-chain, Sanctifier checks the ways those integrations keep breaking: nullifiers that are never recorded, public inputs that don't commit to the transaction, verifying keys with no ceremony provenance or trusted straight out of storage.
Important
→ docs/zk-roadmap.md is the scope summary: which Z-rules have detectors today, which are documented but not yet wired, and what is deliberately deferred. Start there before reading the 62 individual issues.
The full catalogue lives in docs/rules/, with the vulnerability classes and secure patterns explained in the ZK Security Guide.
This isn't a slide deck. Sanctifier's Runtime Guard Wrapper, Reentrancy Guard, and Vulnerable-by-design Contract are deployed and emitting on-chain audit events you can stellar contract invoke against today. See LIVE_TESTNET.md for addresses, verification commands, and event logs.
# Tail real-time guard events on the live deployment
stellar events --network testnet --start-ledger <LATEST> \
--id $RUNTIME_GUARD_CONTRACT_ID| Surface | For | Time to first finding |
|---|---|---|
sanctifier CLI | Local dev, scripts, hot paths | 30 seconds |
| GitHub Action | Every PR, every push | One commit |
| Web Dashboard (Next.js) | Auditors, reviewers, hackathon demos | Drag-and-drop a .rs file |
| VS Code Extension | Inline diagnostics as you type | One install |
| On-chain Runtime Guard | Forensic trail after deploy | One contract wrap |
Same engine under all of them (it cross-compiles to WASM for the browser path), so findings are bit-for-bit identical wherever you scan.
Tip
Skip Z3: You can install without Z3 formal verification by appending --no-default-features to the cargo command.
# 1. install
cargo install sanctifier-cli
# 2. scan
sanctifier analyze ./contracts
# 3. integrate into CI — exit 1 on high/critical findings
sanctifier analyze ./contracts --exit-code --format sarif > sanctifier.sarif
# 4. ship a security badge for your README
sanctifier analyze . --format json > report.json
sanctifier badge --report report.json --svg-output sanctifier.svgWhat you'll see
⚠️ Authentication Gaps
→ [S001] src/lib.rs:transfer — missing require_auth
→ [S001] src/lib.rs:mint — missing require_auth
⚠️ Unchecked Arithmetic
→ [S003] src/lib.rs:transfer:30 — operator `-`
→ [S003] src/lib.rs:transfer:33 — operator `+`
⚠️ SEP-41 Deviation
→ [S012] missing `allowance` function
🛡️ 2 known-vulnerability matches from DB v1.0.0
❌ [SOL-2024-002] Missing auth on token transfer (CRITICAL)
🔴 [SOL-2024-003] Unchecked balance underflow (HIGH)
✨ Scan complete · 4 findings · exit 1
Exit code is 1 when critical/high findings are present — wire it into CI as-is.
# .github/workflows/sanctifier.ymlname: Sanctifieron: [pull_request, push]permissions: { contents: read, security-events: write }jobs:
scan:
runs-on: ubuntu-lateststeps:
- uses: actions/checkout@v4
- uses: HyperSafeD/Sanctifier@mainwith:
path: .format: sarifmin-severity: highupload-sarif: "true"SARIF lands in GitHub code-scanning so reviewers see annotations inline on PRs.
Tip
Ensure you have security-events: write permissions enabled in your GitHub Actions settings for SARIF uploads to succeed.
cd frontend
npm install
npm run dev
# → http://localhost:3000/scan— drag in a.rsfile, get findings in <2s/dashboard— load a JSON report, drill in by severity, see a live call-graph/playground— try canned vulnerable contracts (auth-gap, overflow, unsafe-PRNG, …)/terminal—sanctifierin a terminal emulator for guided demos
Tip
Quick start: For most users, cargo install sanctifier-cli is all you need.
| Method | Command | Best for |
|---|---|---|
| Cargo (recommended) | cargo install sanctifier-cli | Most users; includes Z3 verification |
| Cargo (no Z3) | cargo install sanctifier-cli --no-default-features | Faster install; all rules except S011 work |
| Docker | docker run --rm -v $PWD:/src ghcr.io/hypersafed/sanctifier analyze /src | No local Rust needed |
| GitHub Codespaces |  | Cloud IDE, pre-configured |
| From source | git clone https://github.com/HyperSafeD/Sanctifier && cd Sanctifier && make release | Latest development version |
Direct downloads for your platform (no Rust toolchain required):
| Platform | Download | Verification |
|---|---|---|
| Linux (x86_64) | Download | SHA256 |
| Linux (musl) | Download | SHA256 |
| macOS (Intel) | Download | SHA256 |
| macOS (Apple Silicon) | Download | SHA256 |
| Windows | Download | SHA256 |
Verifying binaries: Each release includes SHA256 checksums for integrity verification:
# Linux/macOS
curl -LO https://github.com/HyperSafeD/Sanctifier/releases/latest/download/sanctifier-linux-amd64
curl -LO https://github.com/HyperSafeD/Sanctifier/releases/latest/download/sanctifier-linux-amd64.sha256
sha256sum -c sanctifier-linux-amd64.sha256
# Windows (PowerShell)
(Get-FileHash sanctifier-windows-amd64.exe).Hash -eq (Get-Content sanctifier-windows-amd64.exe.sha256)Minimum:
- Rust 1.78+ (if installing via cargo)
- 2GB RAM
- 500MB disk space
For full features (including Z3 formal verification):
| Platform | Required Packages |
|---|---|
| Debian/Ubuntu | sudo apt-get install libz3-dev clang libclang-dev build-essential pkg-config |
| Fedora/RHEL | sudo dnf install z3-devel clang clang-devel |
| Arch Linux | sudo pacman -S z3 clang |
| macOS | brew install z3 llvm |
| Windows | Install Z3 and Visual Studio Build Tools |
Optional:
soroban-clifor contract deployment features:cargo install soroban-cliwasm-packfor WASM analysis:cargo install wasm-pack
If you don't need formal verification (rule S011), install without Z3 dependencies:
cargo install sanctifier-cli --no-default-featuresThis reduces installation time and removes the Z3 dependency requirement. All other rules (S001-S010, S012) remain fully functional.
After installation, verify Sanctifier is working:
# Check version
sanctifier --version
# Run environment diagnostics
sanctifier doctor
# Test with a sample scan
sanctifier analyze --helpKeep your installation up-to-date:
# Update via cargo
cargo install sanctifier-cli --force
# Or use built-in updater with integrity checks
sanctifier updateWarning
Common Issues and Fixes
"cargo: command not found"
- Install Rust via rustup:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh - Restart your terminal or run:
source ~/.cargo/env
- Install Rust via rustup:
"failed to compile z3-sys"
- Install Z3 development libraries (see System Requirements above)
- Or install without Z3:
cargo install sanctifier-cli --no-default-features
"sanctifier: command not found" after installation
- Ensure
~/.cargo/binis in your PATH - Add to shell profile:
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
- Ensure
Windows: "VCRUNTIME140.dll not found"
For more detailed troubleshooting, see docs/getting-started.md#troubleshooting.
# Full analysis (most flags shown; all have defaults)
sanctifier analyze [PATH]
--format text|json|sarif|ndjson # output format (default: text)
--limit BYTES # ledger entry size cap (default: 64000)
--timeout SECS # per-file timeout, 0 = none (default: 30)
--exit-code # exit 1 when findings meet threshold
--min-severity critical|high|medium|low # threshold for --exit-code (default: high)
--profile strict|lenient|ci|audit # preset overrides --exit-code/--min-severity
--webhook-url URL # POST results here on completion (repeatable)
--no-cache # skip incremental analysis cache# Other commands
sanctifier diff [PATH] --baseline <report.json># new/resolved findings vs baseline
sanctifier watch [PATH] # re-runs on file change
sanctifier workspace [PATH] # cargo-workspace-aware scan
sanctifier callgraph [PATH] --output callgraph.dot
sanctifier harness [PATH] --output fuzz-harness --target afl|honggfuzz|both
sanctifier badge --report report.json --svg-output sanctifier.svg
sanctifier fix [PATH] --rule S003 # apply patcher fixes
sanctifier verify [PATH] # Z3-only invariant pass
sanctifier deploy [PATH] --network testnet|futurenet|mainnet
sanctifier doctor # environment diagnostics
sanctifier init [PATH] # scaffold project + .sanctify.toml
sanctifier update # self-update with checksum checkEvery subcommand accepts --format json for machine consumption. Use --format ndjson with analyze for streaming line-delimited output (one JSON object per finding, final {"event":"done"}).
--format json output validates against schemas/analysis-output.json (JSON Schema draft-07). Every report carries a schema_version that bumps independently of the CLI version, so downstream tooling can pin to a schema without coupling to a release cadence.
SARIF 2.1.0 output is canonical for GitHub code-scanning and any SAST aggregator.
Note
--format sarif produces a SARIF 2.1.0 document compatible with GitHub code-scanning.
--format ndjson streams one object per finding so large scans can be processed incrementally.
ignore_paths = ["target", ".git"]
enabled_rules = ["auth_gaps", "panics", "arithmetic", "ledger_size"]
ledger_limit = 64000approaching_threshold = 0.8strict_mode = false
[[custom_rules]]
name = "no_unsafe_block"pattern = 'unsafe\s*\{'severity = "error"Custom rules support full YAML DSL — see docs/rule-authoring-guide.md.
Sanctifier is shipping in waves. What's done, what's next, what's wishlist:
- 12 canonical analysis rules (S001–S012) with stable codes
- CLI, GitHub Action, Web Dashboard, VS Code extension, WASM build
- Off-chain anomaly detector for recorded runtime calls with Slack/Discord alerts
- Live testnet runtime-guard contracts emitting on-chain audit events
- SARIF + JSON output, draft-07 schema, badge generator
- Diff mode, watch mode, cargo-workspace scan, patcher
In flight (see the contrib-wave issues)
- Real-LLM provider for
/api/ai/explain(currently stubbed) - Editor-agnostic
sanctifier lspfor Neovim / Helix / Zed - Streaming
--ndjsonoutput for incremental piping - GitHub PR comment formatter with delta vs base
- 20+ new engine rules (allowance race, TTL bumps, cross-contract
try_call, taint through destructures, …) - ZK integration —
Z001..Z014rule catalogue, circom/Noir parsing, shielded-contract fixtures, dashboard ZK panel. Scope and status: docs/zk-roadmap.md
- Hosted REST API, Stellar Laboratory plugin, cargo-sanctify subcommand shim, anomaly-detection rules engine for recorded runtime calls
Sanctifier/
├── tooling/
│ ├── sanctifier-cli/ # CLI binary (the one you install)
│ ├── sanctifier-detector/ # Off-chain anomaly detection service
│ ├── sanctifier-core/ # Static-analysis engine + Z3 backend
│ └── sanctifier-wasm/ # Browser/Node WASM build of the engine
├── frontend/ # Next.js dashboard, playground, terminal
├── vscode-extension/ # VS Code diagnostics integration
├── contracts/ # Soroban contracts (fixtures + live targets)
│ ├── runtime-guard-wrapper/ # ← deployed to testnet
│ ├── reentrancy-guard/ # ← deployed to testnet
│ └── vulnerable-contract/ # ← deployed to testnet (demo target)
├── schemas/
│ └── analysis-output.json # JSON Schema (draft-07) — validated in CI
├── data/
│ └── vulnerability-db.json # Community-sourced CVE-style patterns
├── action.yml # GitHub composite action
├── benchmarks/ # Performance corpora
├── specs/ # OpenAPI + RFC drafts
└── docs/ # Guides, ADRs, threat models, case studies
Scan your first Soroban contract in 5 minutes →
The tutorial walks you through installing Sanctifier, writing a minimal contract, running your first scan, fixing every finding, and confirming a clean report — all in a single terminal session.
| If you want to… | Read |
|---|---|
| Get started (tutorial) | docs/getting-started.md |
| Browse the API reference | API Documentation |
| Understand every finding code | docs/error-codes.md |
| Analyse a ZK contract | docs/zk-roadmap.md (scope) · ZK Security Guide · ZK Integration Guide |
| Wire the runtime guard into your contract | docs/runtime-guards-integration.md |
| Set up CI | docs/ci-cd-setup.md |
| Deploy to testnet | docs/soroban-deployment.md |
| Write your own rule | docs/rule-authoring-guide.md |
| See it benchmarked | docs/case-studies/soroban-examples.md |
| Review the threat model | docs/security-threat-model.md |
| Check service reliability targets | docs/SLO.md — uptime, latency, and error budgets for the hosted API |
| Rollback procedures for mainnet | ROLLBACK_PROCEDURE.md |
| Understand versioning policy | VERSIONING_POLICY.md |
| Browse design decisions | docs/adr/ |
Tip
We're picking up momentum and we want the help. ~100 hand-curated [contrib-wave] issues are live, each one with a problem statement, acceptance criteria, file pointers, and difficulty hint.
There's a good first issue for every skill level — bash, Rust, TypeScript, Next.js, GitHub Actions, doc-writing, contract authoring. Start with CONTRIBUTING.md, then pick an issue and say hi.
MIT — see LICENSE.
{ "metadata": { "version": "0.1.0", "format": "sanctifier-ci-v1", "timestamp": "…" }, "summary": { "critical": 0, "high": 1, "medium": 2, "low": 0 }, "error_codes": ["S001", "S003"], "auth_gaps": [{ "location": "src/lib.rs:42", "message": "missing require_auth" }], "arithmetic_issues": [{ "location": "src/lib.rs:30", "operator": "-" }], "rule_violations": [{ "rule_name": "require_auth_for_args", "severity": "Error", "location": "src/lib.rs:set_admin", "message": "…" }], "vuln_db_matches": [{ "id": "SOL-2024-002", "severity": "CRITICAL", "matched_at": "src/lib.rs:55" }], "schema_version": "1.0.0" }