Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .github/CODEOWNERS
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
# Default owners for the repository.
* @Ayinkx @Ayinkx01

# Release, CI, and security-sensitive paths.
/.github/ @Ayinkx @Ayinkx01
/SECURITY.md @Ayinkx @Ayinkx01
/docs/DRIPS_READINESS.md @Ayinkx @Ayinkx01
/docs/APPEAL.md @Ayinkx @Ayinkx01
63 changes: 63 additions & 0 deletions .github/ISSUE_TEMPLATE/bug.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
name: Bug report
description: Report a reproducible bug in the CLI or libraries
title: "[Bug]: "
labels: ["type/bug"]
body:
- type: markdown
attributes:
value: |
Do not report security vulnerabilities here. Use
https://github.com/StellarFoundry/stellar-devkit/security/advisories/new
- type: input
id: version
attributes:
label: Version
description: Output of `stellar-foundry version`, or the commit SHA.
placeholder: "stellar-foundry 0.1.0 / aec759c"
validations:
required: true
- type: dropdown
id: command
attributes:
label: Command or crate
options:
- doctor
- strkey
- scval
- envelope
- event
- endpoint
- inspect-wasm
- analyze-wasm
- rpc-health
- library API
- build / CI
validations:
required: true
- type: textarea
id: steps
attributes:
label: Steps to reproduce
description: Include the exact command and, for XDR, a minimal input.
validations:
required: true
- type: textarea
id: expected
attributes:
label: Expected behavior
validations:
required: true
- type: textarea
id: actual
attributes:
label: Actual behavior
description: Include the exit code and whether `--format json` changes the output.
validations:
required: true
- type: textarea
id: environment
attributes:
label: Environment
description: OS, Rust version, and whether the input came from a file, stdin, or a live RPC endpoint.
validations:
required: true
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/feature.yml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
name: Feature request
description: Propose a feature or improvement
title: "[Feature]: "
labels: ["type/feature", "triage"]
labels: ["type/feature"]
body:
- type: textarea
id: problem
Expand Down
55 changes: 39 additions & 16 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,23 +7,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [Unreleased]

The workspace version is `0.1.0`. This section describes merged work on `main`;
no tagged release or crates.io publication exists yet.

### Added

- `devkit-core`: structured errors, network profiles, and output formats.
- `devkit-xdr`: bounded base64 decoding for `ScVal`, `TransactionEnvelope`, and
`ContractEvent`, plus strkey classification and malformed-input regression
fixtures.
- `devkit-rpc`: endpoint validation, typed protocol models, deterministic mock
transport, retry policy, and bounded HTTP JSON-RPC transport.
- `devkit-contract`: bounded, non-executing WASM validation and structural
metadata for imports, exports, and custom sections.
- `devkit-analysis`: deterministic structural findings with stable rule IDs
and SARIF 2.1.0 serialization.
metadata for imports, exports, and custom sections, including bounded
`contractspecv0` decoding.
- `devkit-analysis`: deterministic structural findings with stable rule IDs and
SARIF 2.1.0 serialization.
- `devkit-config`: strict TOML configuration parsing, timeout validation,
environment overrides, and static diagnostic events.
- `devkit-rpc`: bounded HTTP JSON-RPC transport with timeout, redirects
disabled, response-size limits, response validation, and structured errors.
- CLI commands `inspect-wasm`, `analyze-wasm`, and `rpc-health`.
- `rpc-health` now consumes bounded TOML configuration, timeout settings, and environment overrides; endpoint precedence is explicit in the CLI reference.
- Release-validation workflow, release checklist, Drips readiness checklist, and manual SARIF upload workflow for GitHub code scanning.
- RustSec dependency auditing and declared Rust 1.91 workspace MSRV in PR #127.
- Malformed-XDR regression corpus and bounded-input hardening.
- CLI commands `endpoint`, `inspect-wasm`, `analyze-wasm`, and `rpc-health`, in
addition to `version`, `doctor`, `strkey`, `scval`, `envelope`, and `event`.
- `rpc-health` consumes bounded TOML configuration, timeout settings, and
environment overrides; endpoint precedence is documented in the CLI reference.
- Release-validation workflow, release checklist, Drips readiness checklist, and
manual SARIF upload workflow for GitHub code scanning.
- RustSec dependency auditing, declared Rust 1.91 workspace MSRV, and a
dedicated MSRV CI job.
- Malformed-XDR regression corpus, bounded-input hardening, and fuzz targets for
`ScVal`, `TransactionEnvelope`, and `ContractEvent`.
- CI: formatting, Clippy, and Linux, Windows, and macOS tests.

### Changed

- Documentation now describes merged work as merged: project status, readiness,
architecture, getting started, roadmap, issue audit, backlog, and Wave board
were regenerated against `main`.
- `docs/WAVE_BOARD.md` now contains only open, independent, Wave-sized issues.
- Added `docs/WHY_DEVKIT.md` to document the boundary with official Stellar
tooling and `soroban-security-scanner`.

### Fixed

- `devkit-xdr`: decoding now applies bounded reader limits instead of
Expand All @@ -33,12 +55,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

### Limitations

- These changes are on open pull-request branches and are not all merged to
`main`.
- No tagged release, release binaries, or crates.io publication exists yet.
- `contractspecv0` XDR entries are decoded into official XDR-JSON definitions
with a variant kind and best-effort name; a normalized ABI schema remains future work.
- Analysis findings are structural heuristics, not a comprehensive
vulnerability detector.
with a variant kind and best-effort name; a normalized ABI schema remains
future work.
- Analysis findings are structural heuristics, not a comprehensive vulnerability
detector.
- SARIF upload requires manual workflow dispatch, a repository-relative WASM
artifact, and GitHub code-scanning permissions.
- The configuration API is currently wired into `rpc-health`; other commands do not consume RPC configuration because they do not need it.
- The configuration API is currently wired into `rpc-health`; other commands do
not consume RPC configuration because they do not make network requests.
14 changes: 10 additions & 4 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ cargo build
cargo test
```

A recent stable Rust toolchain is required.
Rust 1.91 or newer is required (the workspace MSRV).

## Before opening a pull request

Expand All @@ -45,13 +45,19 @@ cargo test --all
## Architecture

Read [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) first. The crate dependency
direction is one-way: `devkit-cli → devkit-xdr → devkit-core`. Do not add a
Stellar dependency to `devkit-core`.
direction is one-way:

```
devkit-cli → devkit-xdr / devkit-rpc / devkit-contract / devkit-analysis / devkit-config
→ devkit-core
```

Do not add a Stellar dependency to `devkit-core`.

## Adding functionality

- Prefer composing with official crates (`stellar-xdr`, `stellar-strkey`, and
later `stellar-rpc-client`) over reimplementing.
`stellar-rpc-client`) over reimplementing.
- Every fallible function returns `devkit_core::DevkitError`.
- Add unit tests; decoding changes must include malformed-input tests.
- Update documentation and `CHANGELOG.md` for user-visible changes.
Expand Down
57 changes: 51 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,18 +9,31 @@ and a CLI.

The core works fully **offline** and never requires AI.

> Status: early. See [docs/PROJECT_STATUS.md](docs/PROJECT_STATUS.md) for exactly
> what works today. Only documented features exist.
> Status: early, pre-release (`0.1.0` in the workspace). The implementation
> described below is merged on `main`. No tagged release or crates.io
> publication exists yet. See [docs/PROJECT_STATUS.md](docs/PROJECT_STATUS.md)
> for exactly what works today. Only documented features exist.

## What works today

- `devkit-core` — shared errors, network profiles, output format.
- `devkit-xdr` — decode `ScVal`, `TransactionEnvelope`, and `ContractEvent` from
base64 XDR into JSON; classify Stellar strkeys.
base64 XDR into JSON; classify Stellar strkeys; bounded malformed-input
handling.
- `devkit-rpc` — endpoint validation, typed protocol layer, deterministic mock
transport, retry policy, and a bounded HTTP JSON-RPC transport.
- `devkit-contract` — non-executing WASM validation, import/export/custom-section
metadata, and bounded `contractspecv0` decoding.
- `devkit-analysis` — deterministic structural findings with stable rule IDs and
SARIF 2.1.0 serialization.
- `devkit-config` — strict TOML parsing, timeout validation, environment
overrides, and secret-safe diagnostics.
- `stellar-foundry` CLI — `version`, `doctor`, `strkey`, `scval`, `envelope`,
`event`.
`event`, `endpoint`, `inspect-wasm`, `analyze-wasm`, and `rpc-health`.
Terminal and JSON output, SARIF output for analysis, and exit codes `0`/`2`/`3`.

Library APIs and CLI commands now include bounded HTTP RPC health checks, structural WASM inspection, deterministic findings with SARIF serialization, and validated TOML configuration. See [docs/IMPLEMENTED_CAPABILITIES.md](docs/IMPLEMENTED_CAPABILITIES.md) for exact scope and known limitations.
See [docs/IMPLEMENTED_CAPABILITIES.md](docs/IMPLEMENTED_CAPABILITIES.md) for
exact scope and known limitations.

## Install and build

Expand All @@ -29,6 +42,12 @@ cargo build --release
./target/release/stellar-foundry version
```

Or install the CLI from the workspace:

```bash
cargo install --path crates/devkit-cli
```

## Usage

```bash
Expand All @@ -37,12 +56,34 @@ stellar-foundry strkey CA3D5KRYM6CB7OWQ6TWYRR3Z4T7GNZLKERYNZGGA5SOAOPIFY6YQGAXE
stellar-foundry scval --format json <BASE64_XDR>
stellar-foundry envelope --format json <BASE64_XDR>
stellar-foundry event --format json <BASE64_XDR>
stellar-foundry endpoint https://soroban-testnet.stellar.org
stellar-foundry inspect-wasm ./contract.wasm
stellar-foundry analyze-wasm --format sarif ./contract.wasm
stellar-foundry rpc-health https://soroban-testnet.stellar.org
```

Exit codes: `0` success, `2` usage error, `3` runtime/decode error.
Decode commands accept `-` to read one bounded value from stdin. Exit codes:
`0` success, `2` usage error, `3` runtime/decode error.

## Scope and limitations

- `contractspecv0` entries are decoded into XDR-JSON definitions with a variant
kind and best-effort name; a normalized ABI schema is future work.
- Analysis rules are structural heuristics, not proof of a vulnerability.
- SARIF upload is a manual workflow and requires a WASM artifact plus
code-scanning permissions.
- RPC configuration is currently consumed by `rpc-health`; other commands do not
make network requests.
- No tagged release, release binaries, or crates.io publication exists yet.

## Relationship to other Stellar tooling

- **Official crates and CLI:** DevKit depends on `stellar-xdr` and
`stellar-strkey` and complements `stellar-cli`; it does not replace them.
- **`soroban-security-scanner`:** DevKit is a developer workflow and inspection
toolkit (XDR, transactions, events, RPC, contract metadata). It is not a
source-level vulnerability scanner. See
[docs/WHY_DEVKIT.md](docs/WHY_DEVKIT.md) for the boundary.

## Design principles

Expand All @@ -54,16 +95,20 @@ Exit codes: `0` success, `2` usage error, `3` runtime/decode error.

## Documentation

- [Why DevKit](docs/WHY_DEVKIT.md)
- [Ecosystem research](docs/ECOSYSTEM_RESEARCH.md)
- [Architecture](docs/ARCHITECTURE.md)
- [Getting started](docs/GETTING_STARTED.md)
- [CLI reference](docs/CLI.md)
- [Configuration](docs/CONFIGURATION.md)
- [Implemented capabilities](docs/IMPLEMENTED_CAPABILITIES.md)
- [Memory measurement](docs/MEMORY.md)
- [Testing guide](docs/TESTING.md)
- [Project status](docs/PROJECT_STATUS.md)
- [Roadmap](docs/ROADMAP.md)
- [Contributing through Drips Wave](docs/WAVE.md)
- [Drips readiness checklist](docs/DRIPS_READINESS.md)
- [Final audit](docs/FINAL_AUDIT.md)

## Contributing

Expand Down
8 changes: 4 additions & 4 deletions crates/devkit-rpc/src/lib.rs
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
//! Stellar RPC protocol layer.
//!
//! This crate models the Stellar RPC JSON-RPC protocol and separates it from
//! transport. It does **not** perform network I/O: a [`Transport`] is injected.
//! A [`MockTransport`] makes RPC-based tooling testable and deterministic, and
//! a production transport (wrapping the official `stellar-rpc-client`) is
//! future work tracked as an issue.
//! transport. A [`Transport`] is injected. [`MockTransport`] makes RPC-based
//! tooling testable and deterministic, and [`HttpTransport`] provides a bounded
//! HTTP JSON-RPC transport. Integrating the official `stellar-rpc-client`
//! remains future work tracked as an issue.
//!
//! Security posture:
//! * Endpoints are validated before use; plaintext `http` is only allowed for
Expand Down
Loading
Loading