apunkt/nyx
1
0
Fork 0
mirror of https://github.com/elicpeter/nyx.git synced 2026-06-09 19:45:13 +02:00
Code Issues Projects Releases Packages Wiki Activity

docs: Enhance module documentation across various files for clarity a… (#62)

Browse source 
* docs: Enhance module documentation across various files for clarity and completeness

* fix: Remove unnecessary blank line in build.rs for cleaner code

* docs: Update documentation to improve clarity and consistency in code comments
This commit is contained in:
Eli Peter 2026-05-02 17:46:45 -04:00 • committed by GitHub
parent 40995e45e7
commit 1f2bfe76c1
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
44 changed files with 721 additions and 366 deletions
Download patch file Download diff file Expand all files Collapse all files

53
src/state/mod.rs
View file

@ -1,4 +1,55 @@
#![doc = include_str!(concat!(env!("OUT_DIR"), "/state.md"))]
//! State-model analysis: resource lifecycle and authentication state tracking.
//!
//! Runs a per-function state machine over the CFG to detect use-after-close,
//! double-close, resource leaks, and unauthenticated access to privileged
//! operations.
//!
//! Enabled by default. Disable via `scanner.enable_state_analysis = false`.
//! Runs in `--mode full` and `--mode taint`; skipped in AST-only mode.
//!
//! # Rule IDs
//!
//! | Rule ID | Severity | What it detects |
//! |---------|----------|-----------------|
//! | `state-use-after-close` | High | Operation on a resource after it was closed |
//! | `state-double-close` | Medium | Resource closed twice |
//! | `state-resource-leak` | Medium | Resource opened and never closed on any path |
//! | `state-resource-leak-possible` | Low | Resource closed on some paths but not others |
//! | `state-unauthed-access` | High | Web handler reaches privileged sink without an auth call |
//!
//! # Managed-resource suppression
//!
//! Language-specific cleanup patterns suppress leak findings automatically:
//!
//! | Pattern | Languages |
//! |---------|-----------|
//! | RAII / Drop | Rust (all leak findings suppressed except `alloc`/`dealloc`) |
//! | Smart pointers (`make_unique`, `make_shared`) | C++ |
//! | `defer f.Close()` | Go |
//! | `with open(f) as f:` | Python |
//! | try-with-resources | Java |
//!
//! # Tracked acquire/release pairs
//!
//! C/C++: `fopen`/`fclose`, `open`/`close`, `socket`/`close`,
//! `malloc`/`free`, `pthread_mutex_lock`/`pthread_mutex_unlock`,
//! `new`/`delete`.
//!
//! Rust: `File::open`/`close`, `TcpStream::connect`/`shutdown`,
//! mutex `lock`/`read`/`write`/`drop`.
//!
//! Java: stream/connection/socket constructors / `close`, `getConnection`/`close`.
//!
//! Go, Python, JavaScript, Ruby, PHP follow language-idiomatic equivalents.
//!
//! # Submodules
//!
//! - [`domain`]: state lattice (`ResourceState`, `AuthState`, `StateCell`)
//! - [`engine`]: generic forward transfer engine (`Transfer` trait, `run_forward`)
//! - [`facts`]: per-node state fact extraction
//! - [`lattice`]: lattice join/meet for state values
//! - [`symbol`]: resource symbol normalisation
//! - [`transfer`]: `DefaultTransfer` — the concrete resource-lifecycle transfer function
pub mod domain;
pub mod engine;