273 lines
14 KiB
Markdown
273 lines
14 KiB
Markdown
# Security, dependency policy, and MSRV
|
|
|
|
This project applies a deliberately small supply-chain hardening policy. It
|
|
tracks the application lockfile, verifies a stable compatibility floor, and
|
|
runs `cargo-audit` plus `cargo-deny`. No other hardening tools are in scope.
|
|
|
|
## Rust compatibility floor
|
|
|
|
The declared and CI-tested minimum supported Rust version (MSRV) is
|
|
**Rust 1.91.0**. This is an LTS-like project policy rather than an upstream Rust
|
|
LTS designation: Rust itself does not publish LTS toolchains.
|
|
|
|
The application code and the former Ratatui 0.28 dependency could be made to
|
|
compile with older compilers, but that graph contained the unmaintained `paste`
|
|
crate and `lru` releases covered by RustSec soundness advisories. Ratatui 0.30.0
|
|
still locked an affected optional `lru` and a vulnerable `time`. Ratatui 0.30.2
|
|
is the first tested upstream line that clears those findings, and it declares
|
|
Rust 1.88.0. That established the previous compatibility floor.
|
|
|
|
On 2026-11-20, [RUSTSEC-2026-0543](https://rustsec.org/advisories/RUSTSEC-2026-0543)
|
|
required removing chrono (all versions are unmaintained). CSV export and the
|
|
hardware-validation example now use jiff, preserving local-time filenames and
|
|
six fractional digits. flexi_logger 0.32 removes its transitive chrono dependency
|
|
and requires Rust 1.91.0, which is the new build and CI floor. Existing logging
|
|
settings remain compatible; source builders must upgrade their Rust toolchain.
|
|
The locked rustix is also updated to at least 1.1.6 for
|
|
[RUSTSEC-2026-0486](https://rustsec.org/advisories/RUSTSEC-2026-0486).
|
|
Neither advisory is ignored.
|
|
|
|
`Cargo.toml` declares `rust-version = "1.91.0"`. CI installs that exact
|
|
toolchain and runs:
|
|
|
|
```console
|
|
cargo +1.91.0 check --locked --all-targets --all-features
|
|
```
|
|
|
|
The normal CI jobs use current stable Rust, while the MSRV job prevents source
|
|
or dependency changes from silently raising the floor. `.cargo/config.toml`
|
|
asks modern Cargo to prefer dependency releases compatible with the declared
|
|
MSRV when the lockfile is deliberately refreshed.
|
|
|
|
## Reproducible dependency graph
|
|
|
|
`Cargo.lock` is tracked because tiny-wb is an executable. All CI compilation,
|
|
test, Clippy, and release-build commands use `--locked`; an uncommitted
|
|
resolution change is therefore a CI error. Do not update dependencies by
|
|
deleting the lockfile casually. After an intentional update, rerun every gate
|
|
in this document and review the lockfile diff.
|
|
|
|
Unused direct dependencies were removed while establishing the lock:
|
|
`clap`, `once_cell`, `ratatui-splash-screen`, and `tui-textarea`. Removing them
|
|
reduces download/build surface and makes policy results describe code that the
|
|
application actually uses. The acquisition refactor also removed direct
|
|
`packed_struct` and `memchr` dependencies: standard-library little-endian
|
|
decoding and buffered framing now provide those functions.
|
|
|
|
## Pinned policy tools
|
|
|
|
CI pins:
|
|
|
|
| Tool | Version | CI command |
|
|
| --- | ---: | --- |
|
|
| `cargo-audit` | 0.22.2 | `cargo audit --deny warnings` |
|
|
| `cargo-deny` | 0.20.2 | `cargo deny check` |
|
|
|
|
The setup stage checks the installed version and installs only when it does not
|
|
match exactly:
|
|
|
|
```console
|
|
cargo install --locked --version 0.22.2 cargo-audit
|
|
cargo install --locked --version 0.20.2 cargo-deny
|
|
```
|
|
|
|
Installing the tools and running both gates requires network access. The audit
|
|
jobs must refresh advisory and registry information; CI must fail rather than
|
|
silently using a stale or unavailable database.
|
|
|
|
## RustSec audit policy
|
|
|
|
`cargo audit --deny warnings` evaluates the complete tracked lockfile against
|
|
the current RustSec database and crates.io yanked status. Warnings such as
|
|
unmaintained or unsound advisories are promoted to failures, as are
|
|
vulnerabilities, yanked packages, database refresh failures, and tool errors.
|
|
|
|
There are no advisory ignores. If a future finding has no upgrade path, adding
|
|
an ignore requires an explicit maintainer decision documenting why tiny-wb is
|
|
unaffected and the condition that will remove the ignore.
|
|
|
|
`cargo-audit` is dependency/advisory matching. It does not prove exploit
|
|
reachability, review application logic, scan native system libraries, or
|
|
replace timely dependency maintenance.
|
|
|
|
## Dependency policy
|
|
|
|
`deny.toml` is evaluated with all features and enforces:
|
|
|
|
- license confidence of 0.8;
|
|
- only licenses currently needed by the resolved graph: Apache-2.0, MIT,
|
|
MPL-2.0, Unicode-3.0, and Zlib;
|
|
- denial of wildcard dependency requirements;
|
|
- warnings for duplicate crate versions;
|
|
- denial of unknown registries and Git sources;
|
|
- crates.io as the only allowed registry and no allowed Git sources;
|
|
- RustSec advisory checks with no ignores;
|
|
- empty crate bans, duplicate skips, license exceptions, and license
|
|
clarifications.
|
|
|
|
The MPL-2.0 allowance is needed by `serialport`. It is a graph-wide allowed
|
|
license, not an exception for one crate.
|
|
|
|
Duplicate warnings remain visible. The reviewed graph currently contains
|
|
transitive version splits for `bitflags`, `hashbrown`, `syn`, `toml`,
|
|
`toml_edit`, `windows-sys`, and `winnow`. They come from incompatible upstream
|
|
constraints in the serial, Ratatui, packed-struct, TOML, and Windows build
|
|
paths. No `skip` entries hide them. Direct `strum` and `thiserror` versions were
|
|
aligned with the graph where the duplicates were avoidable.
|
|
|
|
`cargo-deny` relies on package metadata and configured source URLs. It does not
|
|
perform source-code review, establish legal advice, verify downloaded artifact
|
|
provenance, or find vulnerabilities outside its advisory check.
|
|
|
|
## Local verification
|
|
|
|
Run from the repository root, in this order:
|
|
|
|
```console
|
|
cargo audit --deny warnings
|
|
cargo deny check
|
|
cargo fmt --all -- --check
|
|
cargo +1.91.0 check --locked --all-targets --all-features
|
|
cargo check --locked --all-targets --all-features
|
|
cargo test --locked --all-targets --all-features
|
|
cargo test --locked --no-default-features --lib
|
|
cargo check --locked --no-default-features --features serial --lib
|
|
cargo test --locked --no-default-features --features mock --lib --test mock_device
|
|
cargo test --locked --doc --all-features
|
|
RUSTDOCFLAGS="-D warnings" cargo doc --locked --no-deps --all-features
|
|
cargo clippy --locked --all-targets --all-features -- -D warnings
|
|
cargo build --locked --release --all-features
|
|
```
|
|
|
|
The first two commands require the network. Duplicate-version warnings from
|
|
`cargo deny check` are expected to stay visible and should be reviewed whenever
|
|
the graph changes.
|
|
|
|
## Scope limit
|
|
|
|
This is intentionally “semi-hardened” CI. The repository does not add
|
|
`cargo-vet`, SBOM generation, dependency vendoring, registry proxies,
|
|
provenance/signing systems, or additional security scanners. Expanding that
|
|
scope needs a separate design and maintenance decision.
|
|
|
|
## CI badges and coverage
|
|
|
|
The README references version, tests and line coverage at these mutable URLs:
|
|
|
|
- https://assets.dandaedre.com/coverage/idle-org/tiny-wb/main/version.svg
|
|
- https://assets.dandaedre.com/coverage/idle-org/tiny-wb/main/test.svg
|
|
- https://assets.dandaedre.com/coverage/idle-org/tiny-wb/main/coverage.svg
|
|
|
|
Repository identity and `main` were verified against the origin remote, its
|
|
HEAD, and Gitea repository metadata. The version comes from `Cargo.toml` via
|
|
`cargo metadata --no-deps --locked --format-version 1`, never a Jenkins constant.
|
|
|
|
Coverage uses pinned `cargo-llvm-cov` 0.9.1 and Rust's `llvm-tools-preview`
|
|
component. The worker also needs `jq`. Install the prerequisites and run:
|
|
|
|
```console
|
|
rustup component add llvm-tools-preview
|
|
cargo install --locked --version 0.9.1 cargo-llvm-cov
|
|
mkdir -p coverage
|
|
cargo coverage
|
|
```
|
|
|
|
The exact alias is tracked in `.cargo/config.toml` and expands to:
|
|
|
|
```console
|
|
cargo llvm-cov --locked --all-targets --all-features --ignore-filename-regex /registry/src/ --json --summary-only --fail-under-lines 85 --output-path coverage/summary.json
|
|
```
|
|
|
|
The enforced line-coverage floor is **85%**, measured across the library and
|
|
application without excluding production sources. Local measurement on 2026-11-21
|
|
with the pinned tool was **3,731 of 4,078 lines (91.49%)** after adding loopback
|
|
worker tests for complete single-scan export and live capture, deferred save,
|
|
and graceful shutdown.
|
|
The suite includes library, application, mock/loopback integration and startup
|
|
tests, plus separately run Rustdoc examples. Tests
|
|
cover configuration, protocol, transport, acquisition, export, UI, startup and
|
|
mock device behavior. The floor leaves headroom for platform differences; it is
|
|
not evidence of device/firmware correctness. Version 0.9.1 excludes in-source
|
|
test bodies from the report while retaining every production module, so adding
|
|
tests does not increase the acceptance denominator.
|
|
|
|
`scripts/collect-coverage.sh` runs that command, validates the overall line
|
|
percentage from temporary `coverage/summary.json`, renders the coverage badge,
|
|
and deletes the summary, including on failure. Jenkins then creates the current
|
|
build's test and coverage markers only after unit/integration tests, Rustdoc tests, and the coverage test run succeed.
|
|
The release smoke test remains a nonfatal diagnostic.
|
|
|
|
The collector removes any stale summary before running Cargo and displays only
|
|
`Final line coverage: 91.49%` on success. Compiler and test output is saved to
|
|
ignored `coverage/coverage.log` in the workspace; failures print a short error
|
|
pointing to that log and preserve Cargo's exit status. Missing or invalid
|
|
summaries fail explicitly. No per-file coverage listing is printed, and failed
|
|
runs never render a successful coverage badge.
|
|
|
|
The FreeBSD Jenkins report supplied on 2026-10-05 included 932 crates.io
|
|
source files alongside tiny-wb's 14 source files: 12,243/144,250 covered lines
|
|
(**8.49%**) overall, versus 1,852/2,038 (**90.87%**) for tiny-wb alone.
|
|
Dependency sources under `/root/.cargo/registry/src/` escaped the pinned tool's
|
|
default Cargo-home-based filter. The log does not establish why that default
|
|
filter missed these paths. The alias explicitly filters
|
|
`/registry/src/` paths so dependency caches are excluded regardless of their
|
|
home directory. At that time, all tiny-wb production sources and the **85%** floor
|
|
remained unchanged. This corrected report scope, not test coverage. The subsequent supplied
|
|
FreeBSD Jenkins build #7 confirmed `Final line coverage: 90.87%` and passed the
|
|
coverage stage. That build then stopped at Clippy's `chunks_exact_to_as_chunks`
|
|
lint; the decoder now iterates fixed-size records with `as_chunks::<3>()`,
|
|
compatible with the then-declared Rust 1.88 MSRV. Its exact frame-length validation
|
|
still rejects incomplete records before iteration.
|
|
|
|
FreeBSD Jenkins build #29 used Rust 1.100/LLVM 23 but downgraded the worker's
|
|
0.9.1 installation to the obsolete 0.6.16 pin. Although every test passed, that
|
|
tool reported 29.01%. The retained log does not include per-file totals, so it
|
|
cannot establish the exact files added to the report. Upstream
|
|
[0.9.0](https://github.com/taiki-e/cargo-llvm-cov/releases/tag/v0.9.0) fixed
|
|
build-script files appearing under Cargo's newer build-directory layout, and
|
|
the same CI environment and flags were reproduced locally with 0.9.1 at 91.49%.
|
|
This is a tooling correction, not an exclusion of production code or a
|
|
reduction of the coverage floor.
|
|
|
|
At checkout, CI recreates ignored `coverage/` to remove stale workspace state.
|
|
In `post { cleanup { ... } }`, it uses only current-build markers to choose test
|
|
status and retain measured coverage, falling back to `failing` and neutral `-%`
|
|
when markers are absent. Cleanup reads the version, removes the summary and
|
|
markers, validates and archives exactly `coverage/version.svg`,
|
|
`coverage/test.svg` and `coverage/coverage.svg` with fingerprints and
|
|
`allowEmptyArchive: false`. A later lint/build failure can retain successful
|
|
test/coverage results; these badges report those individual stages.
|
|
|
|
Only `main` publishes to `/mnt/assets/coverage/idle-org/tiny-wb/main/`, with
|
|
`/mnt/assets/coverage` passed as the complete publication root. Publication
|
|
runs in cleanup even after failure. Each file is replaced atomically, with
|
|
0755 new directories and 0644 files; the script never prunes shared assets.
|
|
Concurrent builds of this job are disabled to avoid workspace/marker races.
|
|
|
|
The publication predicate requires a Jenkins **multibranch** job's `BRANCH_NAME`
|
|
and excludes change requests and tags. The actual job configuration is not in
|
|
this repository and remains unverified. When `BRANCH_NAME` is absent,
|
|
publication is skipped with a diagnostic; generation and archival still run.
|
|
Verify the job type and its branch variable before deployment. Real Jenkins
|
|
execution and access to the asset mount remain external deployment checkpoints.
|
|
|
|
The three public URLs were retrieved on 2026-10-05. Each returned HTTP 200 with
|
|
`image/svg+xml` content and parsed as XML. Their accessible labels reported
|
|
version 0.1.1, tests passing, and 90% coverage; the version matched
|
|
`Cargo.toml` as it stood at the time of the check. This confirms that the
|
|
publication endpoint is live, but does not independently verify the external
|
|
Jenkins job configuration or the freshness of its most recent build.
|
|
|
|
Server configuration is external: mount public assets read-only, disable
|
|
directory listing, serve SVG with a restrictive Content-Security-Policy, and
|
|
revalidate mutable URLs or give them a short cache lifetime.
|
|
|
|
Run isolated badge checks with `python3 scripts/test-badges.py`. The renderer
|
|
was copied from `Dandaedre/agent-tasks` at revision
|
|
`fb9d8f7d16f100c2d1377f23394a2302eac9ab18` (retrieved 2026-10-04), with local
|
|
fixes for literal newlines in width measurement, oversized integer validation,
|
|
unique temporary files, directory-output rejection and signal termination.
|
|
|
|
The library feature matrix runs before coverage markers are issued. Mock tests
|
|
require localhost listener permission and never connect to physical hardware.
|