rstix🔗

rstix is the rsigma workspace crate for STIX 2.1 (and future TAXII 2.1 client work). It provides typed Rust objects for all 42 built-in STIX types, bundle ingestion, extension round-trip, and a semantic validation pipeline.

Canonical API reference: docs.rs/rstix. Contributor-facing detail: crate README.

Phase status🔗

Quick start🔗

use std::fs::File;
use std::io::BufReader;

use rstix::model::{Bundle, ValidationCode};
use rstix::parse_bundle;

// String parse (small bundles)
let bundle = parse_bundle(json_str)?;

// Streaming parse (large bundles, e.g. MITRE ATT&CK ~50 MiB)
let file = File::open("enterprise-attack.json")?;
let bundle = Bundle::parse_reader(BufReader::new(file))?;

// MUST rules enforced at parse; SHOULD rules as warnings
let report = bundle.validate();
for warning in report.warnings_with_code(ValidationCode::StixW0031TlpV1Encoding) {
    eprintln!("{}: {}", warning.object_id.as_deref().unwrap_or("?"), warning.message);
}

// Round-trip
let out = serde_json::to_string(&bundle)?;

Pattern Engine (STIX §9)🔗

The optional pattern feature adds STIX patterning: parse, type-check, and evaluate Levels 1–3; canonical printer and Indicator AST wiring follow in later Pattern Engine work.

flowchart LR
    SRC["Pattern string"] --> LEX["lexer.rs"]
    LEX --> PAR["parser.rs<br/>Levels 1–3 AST"]
    PAR --> TCK["typeck.rs<br/>SCO schema + extensions"]
    TCK --> PAT["Pattern::parse"]
    PAT --> AST["PatternAst"]
    AST --> EVAL["eval.rs<br/>Levels 1–3"]
    CTX["context.rs<br/>ObservationContext"] --> EVAL
    EVAL --> OUT["bool match"]

    PAT -.->|"deferred"| PRINT["print.rs"]
    IND["IndicatorPattern::Stix"] -.->|"deferred"| PAT

use rstix::Pattern;
use rstix::pattern::{ObservationContext, TimestampedObservation};

let pattern = Pattern::parse("[ipv4-addr:value = '198.51.100.1/32']")?;
assert_eq!(pattern.observed_types().len(), 1);

// Level 1: single SCO
let sco = /* ... */;
assert!(pattern.matches_single(&sco)?);

// Levels 2–3: timestamped observations
let ctx = ObservationContext::from_scos(&observations);
assert!(pattern.evaluate(&ctx)?);

// Custom SCO types (STIX §9.8) appear in observed_type_names(), not observed_types().
let custom = Pattern::parse("[x-usb-device:usbdrive.serial_number = '1']")?;
assert_eq!(custom.observed_type_names(), vec!["x-usb-device"]);

Build with cargo build -p rstix --features pattern.

In scope (parse + type-check + evaluation)🔗

Lexer, Level 1–3 parser, SCO schema type-checker (18 built-in + custom types), Pattern::parse, Pattern::evaluate, matches_single, matches_single_with_bundle, evaluate_observed_data, ObservationContext, full §9 comparison and temporal semantics (including MATCHES, hex/binary constants), manifest-driven SCO field tests (tests/pattern_eval_sco_fields.rs, 276 cases), per-operator and error-path integration tests, spec §9.8 fixture tests under tests/fixtures/pattern/.

Remaining Pattern Engine work (next slice)🔗

Grammar authority: STIX Specification §9. Internal storage uses PatternAst after type-check.

Evaluation notes (STIX §9):

• TimestampedObservation::at: Option<StixTimestamp>; temporal patterns return MissingTimestamp when any observation lacks a timestamp.
• matches_single_with_bundle: pass a bundle when Level 1 patterns dereference _ref paths.
• Custom SCO types: vendor types (e.g. x-usb-device) deserialize as CustomSco and evaluate nested property paths.
• process:name: resolved from image_ref → file name when a bundle is present, otherwise from the executable token in command_line.
• file:created: alias for ctime.
• network-traffic:dst_ref.type: _ref dereference then type on the target SCO.
• file:hashes.MD5: dictionary dot-key syntax per §9.7.3.
• extensions.'…': predefined SCO extension paths (e.g. windows-pebinary-ext.sections[*].entropy).
• ISSUBSET / ISSUPERSET on string: IP/CIDR subset checks per §9.6.
• Custom SCO types (x-usb-device, …): parsed and type-checked permissively (leaf properties as string).

Tests: tests/fixtures/pattern/ (STIX §9.8), tests/fixtures/pattern/sco-fields/ (SCO field manifest), tests/pattern_parse.rs, tests/pattern_eval.rs, tests/pattern_spec_eval.rs, tests/pattern_eval_operators.rs, tests/pattern_eval_sco_fields.rs, tests/pattern_eval_errors.rs, unit modules pattern::parser::level1, level23, not, pattern::typeck::, pattern::eval, pattern::security.

Later workspace phases (Graph + Marking + Store, TAXII Client) may index indicators by Pattern::observed_types() but do not reimplement pattern grammar.

Public API surface🔗

Crate root (rstix)🔗

core🔗

StixId, 42 typed ID wrappers, StixObjectKind, StixTimestamp, TaxiiTimestamp, Confidence, SpecVersion, LanguageTag, QueryableStixObject, QueryValue.

model🔗

id🔗

Deterministic SCO UUIDv5: select_id_contributing_properties, JCS canonicalization, generate_sco_id, verify_sco_deterministic_id.

vocab🔗

Closed enums (hash algorithms, encryption algorithms, opinion values) and open vocabularies (REGION_OV, malware types, etc.).

Bundle parsing🔗

Methods🔗

Default ParseOptions🔗

Navigation🔗

Plan API name get::<T>() is implemented as get_typed::<T>() to avoid clashing with untyped get.

Custom STIX types🔗

Register extension SDOs per ParseOptions instance (not global):

use rstix::model::{Bundle, BundleObjectCast, ParseOptions, StixObject};

#[derive(serde::Deserialize, serde::Serialize)]
struct XMySdo { /* ... */ }

impl BundleObjectCast for XMySdo {
    fn cast_from(object: &StixObject) -> Option<&Self> {
        match object {
            StixObject::Custom(c) => c.downcast_typed(),
            _ => None,
        }
    }
}

let opts = ParseOptions::new().register_custom_type::<XMySdo>("x-my-sdo");
let bundle = Bundle::parse_with_options(json, &opts)?;

Semantic validation (Bundle::validate)🔗

Parse enforces STIX MUST rules (hard errors). Bundle::validate() collects SHOULD-level and advisory findings without rejecting the bundle.

There is no strict parse flag: permissive parse + explicit validate() is the supported workflow (see maintainer direction on issue #267).

Wire-format validation (pragmatic vs full spec)🔗

STIX SHOULD cite full Internet standards for some string fields. rstix uses lightweight structural checks at parse time — enough to reject obvious garbage without pulling in full IDNA/email parsers.

Why full IDNA / RFC 5322 are not in Data Model + Serialization: they are large, locale-sensitive parsers unrelated to STIX object typing. Basic checks catch malformed CTI early; strict compliance belongs in an optional validation profile or a dedicated dependency (idna, mail-parser, etc.) if a downstream consumer requires it.

Extensions and round-trip🔗

• Top-level x_* keys are peeled before typed deserialize → Bundle::extra_properties(), merged back on serialize.
• toplevel-property-extension keys are hoisted from extensions the same way.
• Standalone leaf deserialize stores unknown keys in common.extra (SDO/SRO/SCO) or MarkingDefinition.extra, drained into extra_properties during bundle parse.

Testing🔗

Run crate tests:

cargo test -p rstix --features serde
cargo test -p rstix --features pattern   # Pattern Engine

Local MITRE ATT&CK corpus (not in git)🔗

The full ATT&CK STIX bundle (~50 MiB) is not committed. CI uses a synthetic 5 000-object streaming test. For local verification, download a bundle (for example MITRE ATT&CK 19.1) and point the integration test at it:

RSTIX_ATTCK_BUNDLE=/path/to/enterprise-attack-19.1.json \
  cargo test -p rstix --features serde attck_corpus_roundtrip_when_present -- --nocapture

This runs parse_reader → serialize → reparse and asserts object count stability. Verified against enterprise-attack-19.1.json (~53 MiB) locally.

STIX version vs TLP marking encoding🔗

Three independent ideas — do not mix them:

A STIX 2.1 bundle can contain marking-definition objects that still use the legacy TLP v1 encoding — that is normal (ATT&CK references the predefined v1 UUIDs).

Full developer guide: crate README — STIX version vs TLP marking encoding.

Model invariants (summary)🔗

Full table: crate README — Model invariant decisions.

• MUST at parse: id/type match, ref resolution in bundle, extension routing, SCO forbidden common props, SDO/SRO time ordering, and type-specific MUST rules documented in ModelError.
• SHOULD via validate(): relationship matrix, CAPEC/CVE, encryption algorithm, TLP v1 warnings, granular selector semantics, language-content rules, location country/region vocabularies, SCO deterministic id.

Feature flags🔗

Related docs🔗

• Architecture — crate map
• Feature flags — rstix
• Fuzzing — fuzz_rstix_parse_bundle
• Crate README