Skip to content

Close public API gaps: nameable field types, reachable no_libc, honest rule-load errors - #23

Open
mnaza wants to merge 2 commits into
marirs:masterfrom
mnaza:fix/public-api-gaps
Open

Close public API gaps: nameable field types, reachable no_libc, honest rule-load errors#23
mnaza wants to merge 2 commits into
marirs:masterfrom
mnaza:fix/public-api-gaps

Conversation

@mnaza

@mnaza mnaza commented Jul 27, 2026

Copy link
Copy Markdown
Contributor

Closes #22.

Small public-API fixes; everything is additive or behavior-preserving for existing callers. New tests/public_api.rs integration test pins the surface (5 tests; total 18 lib + 5 integration, all green).

1. Types in public fields are now nameable downstream

Properties::format / os / arch and FileCapabilities::security_checks exposed types from private modules — downstream could Debug-print them but never match on them. Now re-exported from the crate root:

pub use crate::consts::{FileFormat, Os};
pub use crate::security::options::status::SecurityCheckStatus;
pub use smda::FileArchitecture;

2. FunctionCapabilities getters

address() / features() / capabilities() — fields stay private, so this is additive and non-breaking.

3. no_libc is reachable

BinarySecurityCheckOptions fields are pub(crate) and new() hard-coded no_libc: false — the documented "assume no C runtime" option could not be enabled. New builder-style method:

let opts = BinarySecurityCheckOptions::default().no_libc(true);

4. Rule loading: real parallelism + real errors

The loader thread was spawned after get_file_extractors / Extractor::from_buffer, and smda disassembles eagerly in the constructor — so join blocked immediately and ~1000 YAML rule files loaded strictly serially. The spawn now happens first, overlapping rule loading with format detection + disassembly.

Errors: Ok(Err(_)) | Err(_) => DescriptionEvaluationError threw away the actual failure (bad YAML, missing dependency…) and pointed users at the wrong thing. Now the real RuleSet::new error propagates, and a loader panic is re-thrown via resume_unwind instead of being mislabeled.

5. Strict LibCSpec::from_str

Unknown LSB versions silently became LSB5, changing fortify-check semantics (e.g. 4.0.1 typo). FromStr returns the new Error::InvalidLibCSpec; the lenient From<String> stays for compatibility; capa_cli now uses the strict parse and exits with an error message on bad input.

6. from_file(impl AsRef<Path>)

Was AsRef<str> — non-UTF-8 paths (legal on Unix) could not be analysed. &str/String callers keep compiling; conversion is to_string_lossy internally.

Verified: cargo test --all-features, cargo check --no-default-features / --features verbose, clippy --all-targets — all clean. CHANGELOG entry under [Unreleased]. Based on master; independent of #17 / #19 / #21 except for the shared [Unreleased] CHANGELOG heading.

- pub use FileFormat, Os, FileArchitecture, SecurityCheckStatus from
  the crate root — they appear in public fields but lived in private
  modules, so downstream could not name them.
- FunctionCapabilities: address()/features()/capabilities() getters
  (fields stay private; additive).
- BinarySecurityCheckOptions: builder-style no_libc(bool) — the
  documented option was unreachable (pub(crate) field, new()
  hard-coded false).
- from_file/from_buffer: spawn the rules-load thread BEFORE format
  detection + disassembly so it actually overlaps (smda disassembles
  eagerly; previously join blocked immediately), propagate the real
  RuleSet::new error instead of misreporting DescriptionEvaluationError,
  and resume_unwind a loader panic instead of mislabeling it.
- LibCSpec: strict FromStr (unknown versions error instead of
  silently degrading to LSB5); lenient From<String> kept for compat;
  capa_cli uses the strict parse. New Error::InvalidLibCSpec variant.
- from_file takes impl AsRef<Path> (was AsRef<str>); existing
  &str/String callers keep compiling.

Adds tests/public_api.rs integration tests pinning the public surface.
@mnaza
mnaza force-pushed the fix/public-api-gaps branch from 255d910 to dd9270f Compare July 31, 2026 08:57
@marirs

marirs commented Aug 1, 2026

Copy link
Copy Markdown
Owner

conflicts

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Public API gaps: unnameable types in public fields, dead no_libc option, swallowed rule-load errors, silent LibCSpec fallback

2 participants