docs: fix accuracy drift in SECURITY, ARCHITECTURE, THREAT_MODEL (#253)
Documentation-only accuracy fixes from the codebase audit (no code changes). ## SECURITY.md - Supported-version policy was stale at `0.5.x` while `0.8.3` is published. Bump to the exact `0.8.3` (prose + table `0.8.3 (latest)` / `< 0.8.3`). The exact `x.y.z` form lets `bump_version.py` keep it current automatically (now wired as a touchpoint). ## ARCHITECTURE.md - `three` → **four** binding crates (the C ABI crate was added). - workspace diagram `214` → **514** indicators (matches the `mod`-count and `lib.rs` public-type count; now wired into the indicator-wiring automation so it self-heals). - WASM "does not have automated tests yet" → corrected: `bindings/wasm/src/lib.rs` carries **21** `wasm-bindgen-test` cases. - **Numerical-stability notes rewritten to match the code:** the sliding-window variance family (`StdDev`, `Variance`, `ZScore`, `Bollinger`) uses running `Σx²−mean²` with clamping (and periodic reseed for `Bollinger`), **not** Welford. True Welford is used only by `IntradayVolatilityProfile` and `SeasonalZScore` (it does not transfer cleanly to a sliding window). The **Kahan-summation** bullet is removed — no Kahan summation exists in the crate. ## THREAT_MODEL.md - The C ABI is built with `panic = "abort"` and has no `catch_unwind`. Replace the false "catches panics so none cross the boundary" claim with the honest abort strategy (terminates deterministically instead of unwinding across the FFI boundary, which would be UB).
This commit is contained in:
+16
-13
@@ -7,7 +7,7 @@ for the day-to-day workflow.
|
|||||||
|
|
||||||
## Workspace layout
|
## Workspace layout
|
||||||
|
|
||||||
Wickra is a Cargo workspace of three Rust crates plus three binding crates.
|
Wickra is a Cargo workspace of three Rust crates plus four binding crates.
|
||||||
The split is deliberate: every concern that one user might want to disable
|
The split is deliberate: every concern that one user might want to disable
|
||||||
or replace lives behind a separate crate boundary.
|
or replace lives behind a separate crate boundary.
|
||||||
|
|
||||||
@@ -20,7 +20,7 @@ or replace lives behind a separate crate boundary.
|
|||||||
┌───────────▼──────────┐ ┌──────────▼─────────┐
|
┌───────────▼──────────┐ ┌──────────▼─────────┐
|
||||||
│ wickra-core │ │ wickra-data │
|
│ wickra-core │ │ wickra-data │
|
||||||
│ indicator engine │ │ i/o + aggregation │
|
│ indicator engine │ │ i/o + aggregation │
|
||||||
│ • 214 indicators │ │ • CSV reader │
|
│ • 514 indicators │ │ • CSV reader │
|
||||||
│ • Indicator trait │ │ • Tick aggregator │
|
│ • Indicator trait │ │ • Tick aggregator │
|
||||||
│ • BatchExt impl │ │ • Resampler │
|
│ • BatchExt impl │ │ • Resampler │
|
||||||
│ • OHLCV / Candle │ │ • Live feeds │
|
│ • OHLCV / Candle │ │ • Live feeds │
|
||||||
@@ -203,14 +203,17 @@ typed object arrays for Node/WASM).
|
|||||||
|
|
||||||
A handful of indicators need care beyond naive accumulation:
|
A handful of indicators need care beyond naive accumulation:
|
||||||
|
|
||||||
- **Welford's online variance** is used in `StdDev`, `Variance`, `ZScore`,
|
- **Rolling variance is running-sum, not Welford.** The sliding-window
|
||||||
`BollingerBands`, and several others. Standard sum-of-squares is
|
variance family — `StdDev`, `Variance`, `ZScore`, `Bollinger` — keeps
|
||||||
catastrophically lossy for low-variance inputs; Welford's recurrence
|
running `Σx` and `Σx²` over the window and reports `var = Σx²/n − mean²`,
|
||||||
keeps O(eps) error.
|
clamping to zero the tiny negative values floating-point cancellation can
|
||||||
- **Kahan summation** is used wherever rolling sums could span > 1e6
|
produce. `Bollinger` periodically reseeds its `Σx²` from the live window
|
||||||
elements without resetting — currently only Hurst-exponent's R/S
|
so error cannot accumulate over a long stream. Welford's online algorithm
|
||||||
chunks. Most rolling sums are bounded by the window size and don't need
|
(an incremental `M2` accumulator) does **not** transfer cleanly to a
|
||||||
it.
|
sliding window — removing the oldest point from `M2` is numerically
|
||||||
|
unstable — so it is used only where the statistic is *not* a fixed
|
||||||
|
window: `IntradayVolatilityProfile` and `SeasonalZScore` accumulate
|
||||||
|
per-bucket variance that way.
|
||||||
- **Logarithm bases** matter for some indicators (Hurst, MFI). Wickra
|
- **Logarithm bases** matter for some indicators (Hurst, MFI). Wickra
|
||||||
uses natural log everywhere unless the reference math explicitly
|
uses natural log everywhere unless the reference math explicitly
|
||||||
requires `log10` or `log2` — and then it documents the choice in the
|
requires `log10` or `log2` — and then it documents the choice in the
|
||||||
@@ -327,9 +330,9 @@ re-discovering them.
|
|||||||
- **`FAMILIES` (from PR #60) is hand-maintained.** Adding a new
|
- **`FAMILIES` (from PR #60) is hand-maintained.** Adding a new
|
||||||
indicator requires a separate entry in `FAMILIES`. The
|
indicator requires a separate entry in `FAMILIES`. The
|
||||||
`total_count_matches_expected` test will fail if you forget.
|
`total_count_matches_expected` test will fail if you forget.
|
||||||
- **WASM does not have automated tests yet.** Smoke-validated only
|
- **WASM is covered by `wasm-bindgen-test`.** `bindings/wasm/src/lib.rs`
|
||||||
through the manual examples. Adding `wasm-bindgen-test` coverage is
|
carries 21 in-crate tests (run under `wasm-pack test` in CI), in
|
||||||
on the roadmap.
|
addition to the manual browser examples.
|
||||||
|
|
||||||
For the high-level project goals see [`ROADMAP.md`](ROADMAP.md); for
|
For the high-level project goals see [`ROADMAP.md`](ROADMAP.md); for
|
||||||
day-to-day contribution mechanics see [`CONTRIBUTING.md`](CONTRIBUTING.md).
|
day-to-day contribution mechanics see [`CONTRIBUTING.md`](CONTRIBUTING.md).
|
||||||
|
|||||||
+3
-3
@@ -2,13 +2,13 @@
|
|||||||
|
|
||||||
## Supported versions
|
## Supported versions
|
||||||
|
|
||||||
Wickra is pre-1.0. Security fixes are applied to the latest released `0.5.x`
|
Wickra is pre-1.0. Security fixes are applied to the latest released `0.8.3`
|
||||||
version only; please upgrade to the newest release before reporting an issue.
|
version only; please upgrade to the newest release before reporting an issue.
|
||||||
|
|
||||||
| Version | Supported |
|
| Version | Supported |
|
||||||
| --- | --- |
|
| --- | --- |
|
||||||
| 0.5.x (latest) | :white_check_mark: |
|
| 0.8.3 (latest) | :white_check_mark: |
|
||||||
| older 0.5.x | :x: |
|
| < 0.8.3 | :x: |
|
||||||
|
|
||||||
## Reporting a vulnerability
|
## Reporting a vulnerability
|
||||||
|
|
||||||
|
|||||||
+1
-1
@@ -33,7 +33,7 @@ small.
|
|||||||
| Threat | Mitigation |
|
| Threat | Mitigation |
|
||||||
| --- | --- |
|
| --- | --- |
|
||||||
| Memory-safety exploit (buffer overflow, UAF) via crafted input | Pure safe Rust; `unsafe` is forbidden/minimised, so the compiler precludes these classes. |
|
| Memory-safety exploit (buffer overflow, UAF) via crafted input | Pure safe Rust; `unsafe` is forbidden/minimised, so the compiler precludes these classes. |
|
||||||
| Misuse of the C ABI FFI boundary (invalid/dangling handle, undersized batch buffer) | The C ABI (`bindings/c`) is the sole `unsafe` surface. Its shim adds no logic, NULL-checks every handle (returning `NaN`/no-op), writes only into caller-sized buffers, and catches panics so none cross the boundary. A caller passing a non-NULL but dangling pointer is undefined behaviour by C's own contract — out of scope, the same as any C library. |
|
| Misuse of the C ABI FFI boundary (invalid/dangling handle, undersized batch buffer) | The C ABI (`bindings/c`) is the sole `unsafe` surface. Its shim adds no logic, NULL-checks every handle (returning `NaN`/no-op), writes only into caller-sized buffers, and is built with `panic = "abort"` so a panic terminates the process deterministically instead of unwinding across the FFI boundary (which would be undefined behaviour). A caller passing a non-NULL but dangling pointer is undefined behaviour by C's own contract — out of scope, the same as any C library. |
|
||||||
| 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. |
|
| 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. |
|
| 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. |
|
| Integer overflow / panics | `clippy::pedantic` with `-D warnings`; debug assertions and overflow checks enabled in test/fuzz builds. |
|
||||||
|
|||||||
Reference in New Issue
Block a user