Skip to content

prd.md

Latest commit

 

History

History
125 lines (90 loc) · 4.61 KB

prd.md

File metadata and controls

125 lines (90 loc) · 4.61 KB
Raw

Product Requirements Document (PRD): RytScan

Version: 1.1
Last updated: 2026-08-05
Wave program: Stellar Wave 8 — August 2026

1. Overview

Field Value
Project RytScan
Tagline Soroban security scanner for Stellar smart contracts
Repository BreachDirect/RytScan
Category Security tooling · Static analysis · Soroban

2. Problem Statement

Soroban contracts on Stellar handle real assets. Common vulnerability classes — missing authorization, panic aborts, unchecked token transfers, missing events, TTL archival bugs — recur across Wave repos but are often caught only at review time or after testnet incidents.

Existing tools (OpenZeppelin soroban-scanner, Sanctifier) are powerful but heavyweight. Wave contributors need a fast, zero-config scanner they can run locally and in CI during the 7-day sprint.

3. Drips Wave Alignment

RytScan maps to recurring patterns in the Stellar Wave issue catalog:

Wave pattern RytScan response
Soroban event emission for indexers EVENT-001 rule (Lumenpulse #269)
Contract security before testnet deploy AUTH-001, TOKEN-001, PANIC-001
CI security gates on contract PRs --fail-on high + JSON reports
Backend/indexer reliability Events flagged early reduce silent state changes

Wave 8 goal: Ship Phase 1.5 CLI — 9 detectors, SARIF output for Code Scanning, and CI enforcement — so Wave contributors can gate contract PRs on day one of the sprint.

4. Solution

RytScan provides:

  1. rytscan scan <path> — walk Soroban Rust sources and run security rules
  2. Rule catalog — 9 Phase 1/1.5 detectors aligned with stellar-dev-skill vulnerability classes
  3. Fixture contracts — vulnerable + clean samples for regression tests
  4. CI-ready output — text, JSON, and SARIF v2.1.0 (GitHub Code Scanning), with a configurable failure threshold

5. Target Users

  • Soroban developers submitting Wave PRs
  • Repo maintainers triaging Stellar Wave security issues
  • Auditors doing first-pass static review before deep analysis

6. Phased Delivery

Phase 1: Core CLI & Rule Engine ✅

Deliverable Status
rytscan-core rule engine ✅
rytscan-cli binary (scan, rules) ✅
6 built-in security rules ✅
Vulnerable + clean fixture contracts ✅
PRD + architecture documentation ✅
JSON + text report formats ✅

Success criteria:

  • cargo test passes
  • Scanning fixtures/vulnerable-vault produces ≥ 4 findings
  • Scanning fixtures/clean-token produces 0 high/critical findings
  • rytscan rules lists all rule IDs
  • Documented Wave 8 alignment

Phase 1.5: Rule Expansion & CI Integration ✅

Deliverable Status
ARITH-001, ASSERT-001, UNSAFE-001 rules (9 total) ✅
SARIF v2.1.0 output (--format sarif) ✅
CI workflow (fmt, clippy, tests, fixture smoke) ✅
GitHub Action: BreachDirect/rytscan-action Planned

Success criteria (Phase 1.5):

  • cargo clippy --workspace --all-targets -- -D warnings passes
  • cargo test --workspace passes (12 tests)
  • Vulnerable fixture triggers all 9 rules
  • Clean fixture triggers 0 findings
  • SARIF output validates against the 2.1.0 shape
  • CI gates PRs on fmt + clippy + tests + smoke

Phase 2: AST Analysis & CI Integration

  • Replace line-based heuristics with syn AST traversal
  • GitHub Action: BreachDirect/rytscan-action
  • Rule suppressions via rytscan.toml config

Phase 3: On-Chain Verification

  • WASM size / export surface checks post-build
  • Testnet smoke probes via stellar contract invoke
  • Cross-reference static findings with simulation traces

Phase 4: Platform & Wave Integrator

  • Web dashboard for scan history and severity trends
  • Drips Wave issue matcher (suggest rules from issue title/body)
  • VS Code diagnostics extension

7. Non-Goals (Phase 1)

  • Formal verification (Z3)
  • Runtime on-chain guards
  • Full duplicate of OpenZeppelin detector SDK
  • Web UI

8. Success Metrics

Metric Phase 1 Phase 4
Built-in rules 9 20+
False positive rate (fixtures) ≤ 1 per clean fixture ≤ 5%
Scan time (1 contract) < 100ms < 50ms
Wave repos adopting CI gate 0 10+