🇧🇷 Português

Framework de Segurança Testnet-First para o Ecossistema Stellar + Soroban

🇧🇷 Português · 🇺🇸 English

🇧🇷 Português

"Na Roma antiga, antes que as legiões marchassem para território inimigo, a primeira coisa que construíam era um vallum — uma muralha que separava o seguro do desconhecido."

📖 A Muralha que Veio Antes do Ataque

Existe um momento na vida de todo desenvolvedor Web3 que define o antes e o depois. Não é quando ele escreve a primeira linha de código. Não é quando compila pela primeira vez. É quando ele faz deploy — e percebe que não tem como voltar atrás.

Na blockchain, não existe Ctrl+Z.

Em 2025, $905 milhões foram perdidos em 122 incidentes de smart contracts. Contratos que "funcionavam nos testes". Equipes que confiaram no "parece pronto".

A pergunta não é se seu contrato tem vulnerabilidades. É quais — e se você vai descobri-las antes ou depois de alguém com más intenções.

O StellarVallum responde essa pergunta em dois segundos.

Você abre o terminal. Navega até o diretório do seu projeto — qualquer projeto no ecossistema Stellar. Digita um comando. E a muralha se ergue.

Em menos tempo do que leva para tomar um gole de café, o StellarVallum leu cada arquivo, identificou automaticamente o tipo de projeto, e aplicou nove camadas de verificação alinhadas ao OWASP Smart Contract Top 10 (2026). Encontrou a função sem require_auth. A aritmética sem checked_add. O storage sem TTL. A API key hardcoded na linha 47.

Mas ele não para na análise estática. O SPEAR — o braço ofensivo — pega seu contrato, faz deploy na testnet, e lança sete tipos de ataque real contra ele. Não são simulações. São transações reais, na rede real, com evidência on-chain.

E tudo isso acontece sem que uma única linha do seu código saia da sua máquina.

Porque segurança não é um checkbox no final do processo. É a primeira coisa que você constrói. É a muralha que vem antes do acampamento.

stellarvallum scan --path .

É só isso. A muralha se ergue.

💡 O que é?

StellarVallum é um scanner de segurança para qualquer projeto no ecossistema Stellar + Soroban — smart contracts, dApps, backends, APIs, configs, e pipelines CI/CD.

Ele detecta vulnerabilidades, secrets expostas, e más práticas automaticamente via linha de comando. Gratuito, privado, e instantâneo.

📂 Seu projeto Soroban  →  🔍 stellarvallum scan --path .  →  📊 Relatório de segurança

✨ Destaques

	Feature	Descrição
🆓	Gratuito	Modo No-AI funciona sem API keys
🔒	Privado	Código nunca sai da sua máquina
⚡	Rápido	Análise em < 2 segundos
🎯	Auto-detect	Detecta o tipo de projeto automaticamente
🌐	Multi-perfil	Contratos, dApps, backends, configs, pipelines
🛡️	OWASP	Alinhado ao Smart Contract Top 10 (2026)
🔑	Secrets	Detecta chaves e credenciais hardcoded
⚔️	Adversarial	Testa contra 7 vetores de ataque na testnet

🏗️ Arquitetura

┌──────────────────────────────────────────────────────────────────┐
│                        STELLARVALLUM v0.2.0                        │
├──────────────────────────────────────────────────────────────────┤
│                                                                  │
│  🛡️ SHIELD ─── Análise Estática Multi-Perfil                     │
│  │  ├── 🔐 Access Control (SC01)                                 │
│  │  ├── 📝 Input Validation (SC05)                               │
│  │  ├── 🔗 Unchecked Calls (SC06)                                │
│  │  ├── 🧮 Arithmetic Errors (SC07)                              │
│  │  ├── 🔄 Reentrancy (SC08)                                    │
│  │  ├── ⬆️  Upgradeability (SC10)                                 │
│  │  ├── ⏰ TTL/Archival Risks                                    │
│  │  ├── 💥 Resource Exhaustion                                   │
│  │  └── 🔑 Secret Detection                                     │
│  │                                                               │
│  ⚔️ SPEAR ─── Testes Adversariais na Testnet Real                │
│  │  └── 7 vetores: val_injection, auth_bypass, storage,         │
│  │      cross_contract, replay, resource, front_running          │
│  │                                                               │
│  ⛓️ CHAIN ─── Trilha de Auditoria Imutável (SHA-256)             │
│  │                                                               │
│  📊 DASHBOARD ─── API REST (Axum)                                │
│  │                                                               │
│  🤖 AI ─── Opcional: No-AI (padrão) | OpenRouter | Ollama       │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘

📦 Instalação

Pré-requisitos

🦀 Rust 1.74+
📋 Git

Instalar

git clone https://github.com/catitodev/stellarvallum.git
cd stellarvallum
cargo build --release
cargo install --path .

Verificar

stellarvallum --version
# ⚡ stellarvallum 0.2.0-testnet

🚀 Como Usar

🔍 Scan Automático (recomendado)

Entra no diretório do seu projeto e roda:

stellarvallum scan --path .

O StellarVallum detecta automaticamente o tipo de projeto e aplica as verificações certas:

Tipo Detectado	Quando	O que verifica
🦀 `Contract`	`Cargo.toml` com `soroban-sdk`	OWASP SC Top 10, TTL, resources
🌐 `Dapp`	`package.json` com `react`/`next` + `@stellar/stellar-sdk`	Secrets no frontend, RPC URLs, wallet handling
⚙️ `Backend`	Rust/JS com interação Stellar	HTTP sem TLS, rate limiting, key handling
📄 `Config`	Arquivos `.toml`, `.yaml`, `.env`	Secrets em configs, passphrase errada
🔄 `Pipeline`	`.github/workflows/*.yml`	Secrets em CI, deploy sem approval

📋 Exemplos

# Scan automático (detecta tipo)
stellarvallum scan --path .

# Forçar perfil específico
stellarvallum scan --path ./src --profile contract

# Scan de arquivo único
stellarvallum scan --path ./src/lib.rs

# Salvar relatório JSON
stellarvallum scan --path . -f report.json

# Salvar relatório CSV
stellarvallum scan --path . --output csv -f report.csv

⚔️ Testes Adversariais (SPEAR)

Deploy + ataque real na testnet:

stellarvallum spear \
  --wasm ./target/wasm32-unknown-unknown/release/contrato.wasm \
  --secret-key S...YOUR_TESTNET_SECRET_KEY...

📋 Exemplo de saída

⚔️ SPEAR ADVERSARIAL TESTING
═══════════════════════════════════════
Contract: CABC123...
Network: testnet
Vectors: 7

  [1] val_injection ........... ✅ Resisted
  [2] auth_bypass ............. ✅ Resisted
  [3] storage_exhaustion ...... ✅ Resisted
  [4] cross_contract .......... ✅ Resisted
  [5] replay_attack ........... ✅ Resisted
  [6] resource_probing ........ ✅ Resisted
  [7] front_running ........... ⚠️  Inconclusive

⚔️ CAMPAIGN COMPLETE
  Vulnerabilities: 0
  Status: ✅ All attacks resisted

🚀 Deploy na Testnet

stellarvallum deploy-testnet \
  --wasm ./target/wasm32-unknown-unknown/release/contrato.wasm \
  --secret-key S...YOUR_TESTNET_SECRET_KEY...

📊 Dashboard

stellarvallum dashboard
# → http://127.0.0.1:8501/api/v1/status

Endpoint	Descrição
`GET /api/v1/health`	Health check
`GET /api/v1/status`	Status do sistema, rede, módulos ativos

🛡️ Vulnerabilidades Detectadas

Smart Contracts (OWASP SC Top 10 2026)

	ID	Vulnerabilidade	Severidade
🔐	SC01	Funções sem `require_auth`	🔴 Critical
📝	SC05	`from_val` sem `try_from_val`, Vec/Map sem limites	🟠 High
🔗	SC06	`invoke_contract` sem tratamento de retorno	🟠 High
🧮	SC07	Divisão sem zero-check, aritmética sem checked ops	🟠 High
🔄	SC08	State modificado após `invoke_contract`	🔴 Critical
⬆️	SC10	`update_current_contract_wasm` sem auth	🔴 Critical
⏰	—	Storage sem `extend_ttl`	🟠 High
💥	—	Loops sem limite de iteração	🟠 High
⚠️	—	`panic!` ao invés de `panic_with_error!`	🟠 High

Secrets (Todos os perfis)

	Tipo	Severidade
🔑	Stellar Secret Key (S...)	🔴 Critical
🔑	OpenRouter/OpenAI API Key	🔴 Critical
🔑	AWS Access Key	🔴 Critical
🔑	Private Key (PEM)	🔴 Critical
🔑	JWT Token	🟠 High
🔑	Hardcoded password/secret	🟠 High
🔑	Slack Webhook URL	🟡 Medium

dApps / Backends

	Verificação	Severidade
🌐	RPC URL hardcoded (sem env var)	🟡 Medium
🔓	HTTP sem TLS para endpoints Stellar	🟠 High
🚫	Sem rate limiting	🟡 Medium
💾	Dados sensíveis em localStorage	🟠 High
⚙️	Secret key sem env var	🟠 High

🤖 AI (Opcional)

Modo	Custo	Privacidade	Velocidade
🆓 No-AI (padrão)	Grátis	100%	Instantâneo
🌐 OpenRouter	Pay-per-use	API	~5s
🏠 Local (Ollama)	Grátis	100%	~10s

# config/vallum.toml
[ai]
provider = "none"           # Padrão: gratuito e privado
# provider = "openrouter"   # Opcional: multi-modelo
# provider = "local"        # Opcional: Ollama local

🔐 Segurança do Próprio Projeto

	Medida	Status
🦀	`#![forbid(unsafe_code)]`	✅
🔑	API keys em `Secret<T>` (nunca logadas)	✅
🔒	HTTPS/TLS 1.2+ obrigatório	✅
✅	Validação StrKey (G.../C.../S...)	✅
🧹	CSV sanitizado contra injection	✅
🛤️	Paths validados contra traversal	✅
🌐	Passphrase validada contra RPC real	✅
🧪	21 testes automatizados	✅

💰 Obter XLM de Teste

# 1. Criar keypair: https://lab.stellar.org/
# 2. Fundar (grátis):
curl "https://friendbot.stellar.org?addr=G_SEU_ENDERECO"

💡 O StellarVallum faz isso automaticamente quando necessário.

🗺️ Roadmap

Fase	Versão	Status	Foco
🚧 Beta	v0.2.0	✅ Atual	Testnet, multi-perfil, secrets
👥 Comunidade	v0.3.0	⏳	Bug bounty, mais heurísticas
🔍 Auditoria	v0.4.0	⏳	Audit externo, formal verification
🌐 Mainnet	v1.0.0	⏳	Mainnet unlock, enterprise

🤝 Contribuindo

git clone https://github.com/catitodev/stellarvallum.git
cd stellarvallum
cargo build && cargo test

Áreas prioritárias:

🧩 Novas heurísticas de detecção
🔗 Integração XDR completa para deploy real
🎨 Frontend para o dashboard
🧪 Testes com contratos reais da comunidade
🌍 Traduções

📄 Licença

Apache License 2.0 — veja LICENSE

🔗 Links

	Recurso	URL
📦	Repositório	github.com/catitodev/stellarvallum
🏛️	Vallum Original	github.com/catitodev/vallum
⭐	Stellar Developers	developers.stellar.org
📚	Soroban Docs	developers.stellar.org/docs/build/smart-contracts
🛡️	OWASP SC Top 10	scs.owasp.org/sctop10

🇺🇸 English

"In ancient Rome, before legions marched into enemy territory, the first thing they built was a vallum — a wall that separated the safe from the unknown."

📖 The Wall That Came Before the Attack

There's a moment in every Web3 developer's life that defines the before and after. It's not when they write the first line of code. It's not when they compile for the first time. It's when they deploy — and realize there's no going back.

On the blockchain, there is no Ctrl+Z.

In 2025, $905 million was lost across 122 smart contract incidents. Contracts that "worked in tests". Teams that trusted "looks ready".

The question isn't whether your contract has vulnerabilities. It's which ones — and whether you'll find them before or after someone with bad intentions does.

StellarVallum answers that question in two seconds.

You open the terminal. Navigate to your project directory — any project in the Stellar ecosystem. Type one command. And the wall rises.

In less time than it takes to sip your coffee, StellarVallum has read every file, auto-detected the project type, and applied nine layers of verification aligned with the OWASP Smart Contract Top 10 (2026). It found the function without require_auth. The arithmetic without checked_add. The storage without TTL. The API key hardcoded on line 47.

But it doesn't stop at static analysis. SPEAR — the offensive arm — takes your contract, deploys it to testnet, and launches seven types of real attacks against it. Not simulations. Real transactions, on the real network, with on-chain evidence.

And all of this happens without a single line of your code leaving your machine.

Because security isn't a checkbox at the end of the process. It's the first thing you build. It's the wall that comes before the camp.

stellarvallum scan --path .

That's it. The wall rises.

💡 What is it?

StellarVallum is a security scanner for any project in the Stellar + Soroban ecosystem — smart contracts, dApps, backends, APIs, configs, and CI/CD pipelines.

It detects vulnerabilities, exposed secrets, and bad practices automatically via command line. Free, private, and instant.

📂 Your Soroban project  →  🔍 stellarvallum scan --path .  →  📊 Security report

✨ Highlights

	Feature	Description
🆓	Free	No-AI mode works without API keys
🔒	Private	Code never leaves your machine
⚡	Fast	Analysis in < 2 seconds
🎯	Auto-detect	Detects project type automatically
🌐	Multi-profile	Contracts, dApps, backends, configs, pipelines
🛡️	OWASP	Aligned with Smart Contract Top 10 (2026)
🔑	Secrets	Detects hardcoded keys and credentials
⚔️	Adversarial	Tests against 7 attack vectors on testnet

📦 Installation

Prerequisites

🦀 Rust 1.74+
📋 Git

Install

git clone https://github.com/catitodev/stellarvallum.git
cd stellarvallum
cargo build --release
cargo install --path .

Verify

stellarvallum --version
# ⚡ stellarvallum 0.2.0-testnet

🚀 Usage

🔍 Auto Scan (recommended)

Navigate to your project directory and run:

stellarvallum scan --path .

StellarVallum auto-detects the project type and applies the right checks:

Detected Type	When	What it checks
🦀 `Contract`	`Cargo.toml` with `soroban-sdk`	OWASP SC Top 10, TTL, resources
🌐 `Dapp`	`package.json` with `react`/`next` + `@stellar/stellar-sdk`	Frontend secrets, RPC URLs, wallet handling
⚙️ `Backend`	Rust/JS with Stellar interaction	HTTP without TLS, rate limiting, key handling
📄 `Config`	`.toml`, `.yaml`, `.env` files	Secrets in configs, wrong passphrase
🔄 `Pipeline`	`.github/workflows/*.yml`	Secrets in CI, deploy without approval

📋 Examples

# Auto scan (detects type)
stellarvallum scan --path .

# Force specific profile
stellarvallum scan --path ./src --profile contract

# Single file scan
stellarvallum scan --path ./src/lib.rs

# Save JSON report
stellarvallum scan --path . -f report.json

# Save CSV report
stellarvallum scan --path . --output csv -f report.csv

⚔️ Adversarial Testing (SPEAR)

Deploy + real attack on testnet:

stellarvallum spear \
  --wasm ./target/wasm32-unknown-unknown/release/contract.wasm \
  --secret-key S...YOUR_TESTNET_SECRET_KEY...

📋 Example output

⚔️ SPEAR ADVERSARIAL TESTING
═══════════════════════════════════════
Contract: CABC123...
Network: testnet
Vectors: 7

  [1] val_injection ........... ✅ Resisted
  [2] auth_bypass ............. ✅ Resisted
  [3] storage_exhaustion ...... ✅ Resisted
  [4] cross_contract .......... ✅ Resisted
  [5] replay_attack ........... ✅ Resisted
  [6] resource_probing ........ ✅ Resisted
  [7] front_running ........... ⚠️  Inconclusive

⚔️ CAMPAIGN COMPLETE
  Vulnerabilities: 0
  Status: ✅ All attacks resisted

🚀 Deploy to Testnet

stellarvallum deploy-testnet \
  --wasm ./target/wasm32-unknown-unknown/release/contract.wasm \
  --secret-key S...YOUR_TESTNET_SECRET_KEY...

📊 Dashboard

stellarvallum dashboard
# → http://127.0.0.1:8501/api/v1/status

Endpoint	Description
`GET /api/v1/health`	Health check
`GET /api/v1/status`	System status, network, active modules

🛡️ Detected Vulnerabilities

Smart Contracts (OWASP SC Top 10 2026)

	ID	Vulnerability	Severity
🔐	SC01	Functions without `require_auth`	🔴 Critical
📝	SC05	`from_val` without `try_from_val`, unbounded Vec/Map	🟠 High
🔗	SC06	`invoke_contract` without return handling	🟠 High
🧮	SC07	Division without zero-check, unchecked arithmetic	🟠 High
🔄	SC08	State modified after `invoke_contract`	🔴 Critical
⬆️	SC10	`update_current_contract_wasm` without auth	🔴 Critical
⏰	—	Storage without `extend_ttl`	🟠 High
💥	—	Loops without iteration limit	🟠 High
⚠️	—	`panic!` instead of `panic_with_error!`	🟠 High

Secrets (All profiles)

	Type	Severity
🔑	Stellar Secret Key (S...)	🔴 Critical
🔑	OpenRouter/OpenAI API Key	🔴 Critical
🔑	AWS Access Key	🔴 Critical
🔑	Private Key (PEM)	🔴 Critical
🔑	JWT Token	🟠 High
🔑	Hardcoded password/secret	🟠 High
🔑	Slack Webhook URL	🟡 Medium

dApps / Backends

	Check	Severity
🌐	Hardcoded RPC URL (no env var)	🟡 Medium
🔓	HTTP without TLS for Stellar endpoints	🟠 High
🚫	No rate limiting	🟡 Medium
💾	Sensitive data in localStorage	🟠 High
⚙️	Secret key without env var	🟠 High

🤖 AI (Optional)

Mode	Cost	Privacy	Speed
🆓 No-AI (default)	Free	100%	Instant
🌐 OpenRouter	Pay-per-use	API	~5s
🏠 Local (Ollama)	Free	100%	~10s

# config/vallum.toml
[ai]
provider = "none"           # Default: free and private
# provider = "openrouter"   # Optional: multi-model
# provider = "local"        # Optional: local Ollama

🔐 Project Security

	Measure	Status
🦀	`#![forbid(unsafe_code)]`	✅
🔑	API keys in `Secret<T>` (never logged)	✅
🔒	HTTPS/TLS 1.2+ enforced	✅
✅	StrKey validation (G.../C.../S...)	✅
🧹	CSV sanitized against injection	✅
🛤️	Paths validated against traversal	✅
🌐	Passphrase validated against real RPC	✅
🧪	21 automated tests	✅

💰 Getting Test XLM

# 1. Create keypair: https://lab.stellar.org/
# 2. Fund (free):
curl "https://friendbot.stellar.org?addr=G_YOUR_ADDRESS"

💡 StellarVallum does this automatically when needed.

🗺️ Roadmap

Phase	Version	Status	Focus
🚧 Beta	v0.2.0	✅ Current	Testnet, multi-profile, secrets
👥 Community	v0.3.0	⏳	Bug bounty, more heuristics
🔍 Audit	v0.4.0	⏳	External audit, formal verification
🌐 Mainnet	v1.0.0	⏳	Mainnet unlock, enterprise

🤝 Contributing

git clone https://github.com/catitodev/stellarvallum.git
cd stellarvallum
cargo build && cargo test

Priority areas:

🧩 New detection heuristics
🔗 Full XDR integration for real deployment
🎨 Dashboard frontend
🧪 Testing with real community contracts
🌍 Translations

📄 License

Apache License 2.0 — see LICENSE

🔗 Links

	Resource	URL
📦	Repository	github.com/catitodev/stellarvallum
🏛️	Original Vallum	github.com/catitodev/vallum
⭐	Stellar Developers	developers.stellar.org
📚	Soroban Docs	developers.stellar.org/docs/build/smart-contracts
🛡️	OWASP SC Top 10	scs.owasp.org/sctop10

⚡ TESTNET ONLY — Mainnet support coming in v1.0

_{Built with 🦀 Rust · Secured by 🛡️ StellarVallum · Powered by ⭐ Stellar}

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
.github/workflows		.github/workflows
assets/image		assets/image
config		config
contracts/testnet		contracts/testnet
docs		docs
reports		reports
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
.gitleaks.toml		.gitleaks.toml
.pre-commit-config.yaml		.pre-commit-config.yaml
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
PROJECT_SUMMARY.md		PROJECT_SUMMARY.md
README.md		README.md
SECURITY.md		SECURITY.md
SECURITY_DEPENDENCIES.md		SECURITY_DEPENDENCIES.md
stellarvallum.code-workspace		stellarvallum.code-workspace

Folders and files

Latest commit

History

Repository files navigation

🇧🇷 Português

📖 A Muralha que Veio Antes do Ataque

💡 O que é?

✨ Destaques

🏗️ Arquitetura

📦 Instalação

Pré-requisitos

Instalar

Verificar

🚀 Como Usar

🔍 Scan Automático (recomendado)

📋 Exemplos

⚔️ Testes Adversariais (SPEAR)

🚀 Deploy na Testnet

📊 Dashboard

🛡️ Vulnerabilidades Detectadas

Smart Contracts (OWASP SC Top 10 2026)

Secrets (Todos os perfis)

dApps / Backends

🤖 AI (Opcional)

🔐 Segurança do Próprio Projeto

💰 Obter XLM de Teste

🗺️ Roadmap

🤝 Contribuindo

📄 Licença

🔗 Links

🇺🇸 English

📖 The Wall That Came Before the Attack

💡 What is it?

✨ Highlights

📦 Installation

Prerequisites

Install

Verify

🚀 Usage

🔍 Auto Scan (recommended)

📋 Examples

⚔️ Adversarial Testing (SPEAR)

🚀 Deploy to Testnet

📊 Dashboard

🛡️ Detected Vulnerabilities

Smart Contracts (OWASP SC Top 10 2026)

Secrets (All profiles)

dApps / Backends

🤖 AI (Optional)

🔐 Project Security

💰 Getting Test XLM

🗺️ Roadmap

🤝 Contributing

📄 License

🔗 Links

About

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages