diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 52064d8..5ba33dc 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -108,3 +108,41 @@ jobs: cache-on-failure: true - name: cargo check --target wasm32v1-none (contracts) run: cargo check ${{ env.CONTRACTS }} --target wasm32v1-none + + security-audit: + name: Security audit + runs-on: ubuntu-latest + timeout-minutes: 15 + steps: + - uses: actions/checkout@v4 + - name: Install Rust toolchain + uses: dtolnay/rust-toolchain@stable + with: + cache: false + - name: Cache cargo registry and target + uses: Swatinem/rust-cache@v2 + with: + cache-on-failure: true + - name: Install cargo-audit + run: cargo install cargo-audit --locked + - name: cargo audit + run: cargo audit + + license-check: + name: License check + runs-on: ubuntu-latest + timeout-minutes: 15 + steps: + - uses: actions/checkout@v4 + - name: Install Rust toolchain + uses: dtolnay/rust-toolchain@stable + with: + cache: false + - name: Cache cargo registry and target + uses: Swatinem/rust-cache@v2 + with: + cache-on-failure: true + - name: Install cargo-deny + run: cargo install cargo-deny --locked + - name: cargo deny check + run: cargo deny check diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..daed4c0 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,130 @@ +# Contributing to OrbitChain + +Thank you for your interest in contributing to OrbitChain! This document outlines the development workflow, prerequisites, and guidelines. + +## Prerequisites + +Before setting up the project, ensure you have the following tools installed: + +### Required + +- **Rust toolchain** (stable) — managed automatically by `rust-toolchain.toml` + ```bash + curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh + ``` +- **wasm32v1-none target** — auto-installed when running `rustup show` in the project root +- **`stellar-cli`** — for contract deployment and interaction + ```bash + cargo install --locked stellar-cli --features opt + ``` + +### Security Scanning Tools + +These tools are required to run `make audit` and `make deny` locally. CI jobs install them automatically. + +- **`cargo-audit`** — vulnerability scanning + ```bash + cargo install cargo-audit --locked + ``` +- **`cargo-deny`** — license compliance and policy checks + ```bash + cargo install cargo-deny --locked + ``` + +## Getting Started + +1. **Fork and clone the repository** + + ```bash + git clone https://github.com/YOUR_USERNAME/OrbitChain-Contracts.git + cd OrbitChain-Contracts + ``` + +2. **Verify the toolchain** + + ```bash + rustup show + ``` + +3. **Build the project** + + ```bash + make build + ``` + +4. **Run tests** + + ```bash + make test + ``` + +## Development Workflow + +### Branch Naming + +Use conventional branch names: + +- `feat/` — new features +- `fix/` — bug fixes +- `docs/` — documentation updates +- `refactor/` — code refactoring +- `chore/` — maintenance tasks + +### Commit Messages + +Use [conventional commits](https://www.conventionalcommits.org/): + +``` +feat: add wallet connection modal +fix: resolve donation API error +docs: update project README +refactor: clean up project creation form +``` + +### Before Submitting a Pull Request + +1. Ensure the project builds successfully: + ```bash + make build + ``` + +2. Run all tests and ensure they pass: + ```bash + make test + ``` + +3. Format your code: + ```bash + make fmt + ``` + +4. Run the linter and fix any warnings: + ```bash + make lint + ``` + +5. Run security scans (requires `cargo-audit` and `cargo-deny`): + ```bash + make audit + make deny + ``` + +## Pull Request Process + +1. Create a branch from `main` with a descriptive name. +2. Make your changes and commit them with conventional commit messages. +3. Push your branch to your fork. +4. Open a pull request against the `main` branch of the upstream repository. +5. Ensure all CI checks pass (including security scans). +6. Request review from the maintainers. + +## Code Style + +- Follow Rust's standard formatting (`rustfmt`) — run `make fmt` before committing. +- Adhere to Clippy lint recommendations — run `make lint` to check. +- Write documentation comments for public APIs. +- Add unit tests for new functionality. + +## Questions? + +If you have questions or need help, open a GitHub Discussion or reach out to the maintainers. diff --git a/Makefile b/Makefile index 44b233c..c78f95e 100644 --- a/Makefile +++ b/Makefile @@ -7,7 +7,7 @@ ## make clippy - Lint code .PHONY: build build-wasm build-tools test fmt lint clean optimize help \ - setup deploy-testnet deploy-sandbox sandbox-start audit deny + setup deploy-testnet deploy-sandbox sandbox-start audit deny audit-ci deny-ci # Default target build: build-wasm build-tools @@ -82,12 +82,36 @@ deploy-testnet: build-wasm # Run cargo-audit for vulnerability scanning audit: + @if ! command -v cargo-audit >/dev/null 2>&1; then \ + echo "❌ cargo-audit not installed. Run 'cargo install cargo-audit --locked' then retry." >&2; \ + exit 1; \ + fi @echo "🔒 Running security audit..." cargo audit @echo "✅ Security audit passed" # Run cargo-deny for license compliance deny: + @if ! command -v cargo-deny >/dev/null 2>&1; then \ + echo "❌ cargo-deny not installed. Run 'cargo install cargo-deny --locked' then retry." >&2; \ + exit 1; \ + fi + @echo "📋 Checking license compliance..." + cargo deny check + @echo "✅ License check passed" + +# Security audit (CI variant — installs tool if missing) +audit-ci: + @echo "🔒 Installing cargo-audit (CI)..." + cargo install cargo-audit --locked 2>&1 | tail -1 + @echo "🔒 Running security audit..." + cargo audit + @echo "✅ Security audit passed" + +# License check (CI variant — installs tool if missing) +deny-ci: + @echo "📋 Installing cargo-deny (CI)..." + cargo install cargo-deny --locked 2>&1 | tail -1 @echo "📋 Checking license compliance..." cargo deny check @echo "✅ License check passed" @@ -113,4 +137,6 @@ help: @echo " make deploy-sandbox - Deploy contract to local sandbox" @echo " make deploy-testnet - Deploy contract to Stellar testnet" @echo " make optimize - Optimize WASM with wasm-opt -Oz" + @echo " make audit - Run cargo audit (requires cargo-audit)" + @echo " make deny - Run cargo deny (requires cargo-deny)" @echo " make help - Show this help message" diff --git a/README.md b/README.md index 8cc493d..29637fb 100644 --- a/README.md +++ b/README.md @@ -536,6 +536,18 @@ Open a Pull Request from your fork back to the main branch. This project uses `cargo-audit` and `cargo-deny` to maintain high security standards and license compliance. +### Prerequisites + +Before running security scans locally, install the required tools: + +```bash +# Install cargo-audit for vulnerability scanning +cargo install cargo-audit --locked + +# Install cargo-deny for license and policy compliance +cargo install cargo-deny --locked +``` + ### Local Scans You can run the security scans locally using the following commands: @@ -567,7 +579,7 @@ If a license or ban policy violation is found: ### Automated CI -Security scans are automatically run on every push and pull request. CI will fail if any known vulnerabilities or policy violations are detected. +Security scans are automatically run on every push and pull request via dedicated CI jobs. The CI pipeline installs `cargo-audit` and `cargo-deny` automatically before running the scans. CI will fail if any known vulnerabilities or policy violations are detected. # 📜 License diff --git a/campaign/Cargo.toml b/campaign/Cargo.toml index 993d32e..fd9d214 100644 --- a/campaign/Cargo.toml +++ b/campaign/Cargo.toml @@ -2,6 +2,8 @@ name = "orbitchain-campaign" version = "0.1.0" edition = "2021" +license = "MIT" +publish = false description = "OrbitChain campaign smart contract — milestones, donations, refunds, and lifecycle" [lib] diff --git a/common/Cargo.toml b/common/Cargo.toml index 62d0b73..637eb7b 100644 --- a/common/Cargo.toml +++ b/common/Cargo.toml @@ -2,6 +2,8 @@ name = "orbitchain-common" version = "0.1.0" edition = "2021" +license = "MIT" +publish = false description = "OrbitChain common types — shared CampaignStatus, MilestoneStatus, AssetInfo, and ErrorCode" [lib] diff --git a/crates/contracts/core/Cargo.toml b/crates/contracts/core/Cargo.toml index 99856a0..cf7079a 100644 --- a/crates/contracts/core/Cargo.toml +++ b/crates/contracts/core/Cargo.toml @@ -3,6 +3,8 @@ name = "orbitchain-core" version.workspace = true edition.workspace = true rust-version.workspace = true +license = "MIT" +publish = false description = "Legacy OrbitChain campaign reference contract; canonical implementation lives in orbitchain-campaign" [lib] diff --git a/crates/tools/Cargo.toml b/crates/tools/Cargo.toml index cf490c1..f3dec44 100644 --- a/crates/tools/Cargo.toml +++ b/crates/tools/Cargo.toml @@ -3,6 +3,8 @@ name = "orbitchain-tools" version.workspace = true edition.workspace = true rust-version.workspace = true +license = "MIT" +publish = false description = "OrbitChain CLI tools — key management, signing, asset issuing, and payment processing" [[bin]] diff --git a/deny.toml b/deny.toml new file mode 100644 index 0000000..1f9800a --- /dev/null +++ b/deny.toml @@ -0,0 +1,59 @@ +# cargo-deny configuration +# Run `cargo deny check` to verify license compliance + +[advisories] +# Advisories to ignore (after review) +ignore = [ + # dotenv v0.15.0 is unmaintained (RUSTSEC-2021-0141); + # used by orbitchain-tools for environment variable loading + "RUSTSEC-2021-0141", +] +# How to handle yanked crates: deny, warn (default), or allow +yanked = "warn" +# How to handle unmaintained advisories: all, workspace, transitive, none +unmaintained = "workspace" +# How to handle unsound advisories: all, workspace (default), transitive, none +unsound = "workspace" +# Warn about unused ignored advisories +unused-ignored-advisory = "warn" + +[licenses] +# List of allowed licenses. +# See https://spdx.org/licenses/ for full list. +allow = [ + "MIT", + "Apache-2.0", + "Apache-2.0 WITH LLVM-exception", + "BSD-2-Clause", + "BSD-3-Clause", + "Unicode-3.0", + "Unlicense", + "Zlib", +] +# Confidence threshold for license detection (0.0 - 1.0) +confidence-threshold = 0.8 +# Warn about unused allowed licenses +unused-allowed-license = "warn" + +# Specific exceptions for crates that need additional licenses +# [[licenses.exceptions]] +# allow = ["License-Id"] +# crate = "crate-name" + +[bans] +# Specific crates that are banned +deny = [ + # Example: { name = "openssl", reason = "Using rustls instead" }, +] +# Skip these specific crates from being checked +skip = [] +# Skip entire trees +skip-tree = [] + +[sources] +# Only allow crates from crates.io by default +allow-registry = ["https://github.com/rust-lang/crates.io-index"] +# Deny unknown registries +unknown-registry = "deny" +# Deny git sources unless explicitly allowed +unknown-git = "deny" diff --git a/token-bridge/Cargo.toml b/token-bridge/Cargo.toml index f76e7f1..d806888 100644 --- a/token-bridge/Cargo.toml +++ b/token-bridge/Cargo.toml @@ -2,6 +2,8 @@ name = "orbitchain-token-bridge" version = "0.1.0" edition = "2021" +license = "MIT" +publish = false description = "OrbitChain cross-chain token bridge contract" [lib]