From 404bcb040cd691d192bc797f802343fe9674d391 Mon Sep 17 00:00:00 2001 From: kingchenc Date: Wed, 3 Jun 2026 22:40:56 +0200 Subject: [PATCH] docs: add threat model and security policies (#167) Add THREAT_MODEL.md and SECURITY.md sections: secrets management, release verification, end-of-support, dependency/code-scanning remediation policy, and a VEX statement. Closes OSPS Baseline L3 documentation gaps (SA-03.02, BR-07.02, DO-03.01/03.02/05.01, VM-04.02/05.01/05.02/06.01). Additive only. --- SECURITY.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++ THREAT_MODEL.md | 54 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 115 insertions(+) create mode 100644 THREAT_MODEL.md diff --git a/SECURITY.md b/SECURITY.md index 43bfcf15..f3e03595 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -76,3 +76,64 @@ artifacts, and (4) a healthy dependency supply chain. an exchange using the platform TLS library; transport security therefore depends on that library, not on Wickra. Wickra is not a trading system and is provided "as is" — see the disclaimers in `README.md` and the licenses. + +## Secrets management + +The project stores **no** secrets or credentials in the version control system. +Secrets required by automation (publishing tokens, the about-sync PAT) are kept +exclusively as **GitHub Actions encrypted secrets** and referenced via the +`secrets.*` context; they are never written to the repository, logs, or build +artifacts. GitHub **secret scanning with push protection** is enabled to block +accidental commits of credentials. Secrets follow least privilege (the narrowest +scope that works) and are rotated when a holder changes or on suspected +exposure. + +## Verifying releases + +Released artifacts can be verified for integrity and authenticity: + +- **Build provenance.** Release assets carry GitHub build provenance + attestations. Verify a downloaded asset with the GitHub CLI: + `gh attestation verify --repo wickra-lib/wickra`. +- **Signed tags.** Each release corresponds to a signed git tag (`vX.Y.Z`); + the tag signature identifies the maintainer who authorised the release. +- **Registry integrity.** Packages are distributed over HTTPS from crates.io, + PyPI and npm, which serve package checksums that package managers verify on + install. + +The release is published only by the maintainer through the tag-triggered +release workflow, so a verified tag signature establishes the expected +publisher identity. + +## Support timeline and end of support + +Wickra is **pre-1.0**: only the **latest released `0.y.z`** version receives +security fixes. When a newer release is published, the previous version +**immediately reaches end of support** and will not receive further fixes; +users should upgrade to the latest release. The supported-versions table above +is authoritative. After the `1.0.0` release this policy will be revised to +support a defined window of releases. + +## Remediation policy (dependencies and code scanning) + +- **Severity threshold.** Vulnerabilities of **medium severity or higher** in + the project's own code or its dependencies are remediated promptly and before + the next release; lower-severity findings are addressed on a best-effort + basis. +- **Automated enforcement (SCA).** Every change is evaluated by `cargo-deny` + (RUSTSEC advisories + license policy) and Dependabot; a known-vulnerable + dependency fails CI and **blocks the change** until resolved or explicitly + waived with justification. +- **Automated enforcement (SAST).** Every change is evaluated by CodeQL and + Clippy (`-D warnings`); findings **block the change** in CI until fixed. +- **Pre-release gate.** A release is not cut while an unresolved medium-or-higher + SCA/SAST finding is outstanding. + +## Vulnerability exploitability (VEX) + +Advisories reported by `cargo-deny`/Dependabot for third-party dependencies that +do **not** affect Wickra (e.g. the vulnerable code path is not reachable, or the +affected feature is not enabled) are triaged and recorded — with the +not-affected justification — in the `cargo-deny` configuration (`deny.toml`) and +the relevant pull request, rather than forcing an unnecessary dependency bump. +This serves as the project's exploitability (VEX) record. diff --git a/THREAT_MODEL.md b/THREAT_MODEL.md new file mode 100644 index 00000000..ab90e051 --- /dev/null +++ b/THREAT_MODEL.md @@ -0,0 +1,54 @@ +# Threat model + +This document describes Wickra's attack surface and the threats considered, +together with their mitigations. It complements the security assurance case in +[`SECURITY.md`](SECURITY.md). Wickra is a computational technical-analysis +library (a Rust core with Python, Node.js and WebAssembly bindings), not a +network service or trading system; the attack surface is correspondingly small. + +## Assets + +- **Integrity of computed indicator values** — consumers may use them in + automated decisions, so silently wrong output is the primary concern. +- **Availability of the calling process** — a library must not crash or hang + its host on malformed input. +- **Integrity of published artifacts** — the crates, wheels and npm packages + users install. +- **The build and release pipeline** and its secrets (publishing tokens). + +## Actors / trust boundaries + +- **Library consumer** (trusted) — calls the API with numeric data. Data may + originate from untrusted sources (e.g. a market feed), so *input values* are + treated as untrusted even though the caller is trusted. +- **Optional live feed** — with the `live-binance` feature, data crosses a + network boundary from an exchange over TLS. +- **Contributors** (semi-trusted) — propose changes via pull requests. +- **Supply chain** — upstream dependencies and the CI/CD platform. + +## Threats and mitigations + +| Threat | Mitigation | +| --- | --- | +| Memory-safety exploit (buffer overflow, UAF) via crafted input | Pure safe Rust; `unsafe` is forbidden/minimised, so the compiler precludes these classes. | +| Denial of service via malformed/degenerate input (NaN, infinities, extreme magnitudes) | Indicators reject non-finite inputs and validate parameters at construction; update paths are exercised by coverage-guided fuzzing and unit tests for edge cases. | +| Silently incorrect results | 100% line coverage on the core crate; reference-value tests against known-good sources; streaming/batch parity tests. | +| Integer overflow / panics | `clippy::pedantic` with `-D warnings`; debug assertions and overflow checks enabled in test/fuzz builds. | +| Adversary-in-the-middle on the optional live feed | Connection uses TLS via the platform library; transport security is delegated to that reviewed implementation. | +| Compromised dependency (supply chain) | Dependencies pinned (`Cargo.lock`, hash-locked CI requirements), monitored by Dependabot, audited by `cargo-deny` (advisories + licenses) on every change. | +| Malicious or accidental change to `main` | Branch protection requires signed commits and blocks force-push and deletion; all changes flow through pull requests with required CI; static analysis (CodeQL, Clippy) and fuzzing run on every change. | +| Compromised CI / leaked secrets | Workflows use least-privilege `permissions:`; secrets live only as encrypted GitHub Actions secrets; secret scanning with push protection is enabled; workflows are linted by `zizmor`. | +| Tampered release artifact | Releases are built in CI, tags are signed, and assets carry build provenance attestations (verifiable with `gh attestation verify`). | + +## Out of scope + +- Wickra implements no authentication, authorization or cryptography of its own, + stores no user data, and exposes no network listener; those threat classes do + not apply. +- Vulnerabilities in third-party dependencies that do not affect Wickra are + tracked as exploitability (VEX) records (see [`SECURITY.md`](SECURITY.md)). + +## Maintenance + +This threat model is reviewed when the architecture changes materially (for +example, a new input family, a new network feature, or a new release channel).