rullst-security 12.3.0

Runtime application security, RASP, OWASP headers, Login Jail, and WAF middleware for Rullst.
Documentation

Rullst Security ๐Ÿ›ก๏ธโšก

rullst-security is the dedicated security suite for the Rullst Framework. It uses bounded in-memory state, established cryptographic primitives, and defense-in-depth middleware. Its WAF/RASP rules are heuristic controls and must be combined with secure application design, authentication, authorization, TLS, monitoring, and timely dependency updates.


๐ŸŒŸ Modules & Features

๐Ÿฏ 1. Rullst Honey (rullst::security::honey)

Deception Security & Botnet Mitigation Engine

  • Synthetic Honeypot Traps: Intercepts reconnaissance bots attempting to scan paths like /.env, /admin.php, /wp-login.php, /.git/config.
  • Bounded In-Memory Ban List: Tracks verified socket peers with an explicit TTL and cardinality limit. A request checks only its own peer; expired bans are pruned in expiry order when bans are added or counted, and a full list evicts the ban that expires soonest.
  • Exact Route Matching: Trap paths are matched as complete paths; untrusted forwarding headers are not used as ban identities.
  • Lure-Resistant Bans: Every trap hit is refused, but only a direct request bans its peer. A load that a page initiated (Sec-Fetch-Site of same-origin, same-site or cross-site, or Origin/Referer from a browser without fetch metadata) is recorded without a ban, so an <img src="/.env"> on another site or in user content cannot ban visitors or a shared NAT address. These headers are client-controlled: a scanner can avoid the ban, not the refusal, by sending them.

๐Ÿงน 2. Rullst Sanitizer (rullst::security::sanitizer)

XSS Prevention & Dynamic CSP Nonces

  • Allowlisted HTML Sanitization: Uses ammonia to strip scripts, inline event handlers, unsafe attributes, and unsupported SVG/HTML instead of trying to make arbitrary markup safe.
  • Dynamic Content Security Policy (CSP): Generates cryptographically secure base64 nonces (nonce-<random>) per HTTP request.
  • Clickjacking & Security Headers: Enforces X-Frame-Options: DENY, X-Content-Type-Options: nosniff, and strict Referrer-Policy.

๐Ÿ›ก๏ธ 3. Rullst RBAC Guard (rullst::security::rbac)

Role-Based Access Control & BOLA/IDOR Defense

  • Declarative Authorization: Inspects UserContext roles and fine-grained capabilities (RbacGuard::authorize).
  • BOLA / IDOR Prevention: Provides RbacGuard::authorize_owner_or_role to enforce resource ownership boundaries dynamically.

๐Ÿ“œ 4. Rullst Audit Log (rullst::security::audit)

HMAC-SHA256 Tamper-Evident Trail

  • Canonical Event Chaining: Signs a versioned, domain-separated, length-prefixed encoding of the sequence, timestamp, event fields, and predecessor hash.
  • Offline Integrity Checks: verify_record checks one record's HMAC; verify_sequence additionally validates genesis, monotonic sequence IDs, and predecessor continuity.
  • Extensible Sinks: Provides AuditLogger trait for database ORM logging or Cloud-Native stdout/JSON sinks.

๐Ÿ”‘ 5. TOTP Recovery Codes (rullst::security::recovery_codes)

  • One-time plaintext: 80-bit codes are returned only during enrollment and zeroized on drop.
  • Storage-safe records: Persist only the subject-bound salted HMAC-SHA256 verifiers.
  • Single-use contract: consume_recovery_code removes one verifier; database-backed callers must make compare-and-delete transactional.

๐Ÿ“ฒ 6. MFA & Login Abuse Controls

  • TOTP enrollment: OS-random 160-bit secrets, RFC 6238 code generation, constant-time six-digit verification, otpauth:// URIs, and bounded SVG QR generation through build_mfa_qr_svg.
  • TOTP replay is the caller's job: verify_totp_code is stateless and accepts the previous, current and next 30-second step, so an observed code verifies again for about 90 seconds. To meet RFC 6238 section 5.2, find the matched step with mfa::generate_totp_at_counter, persist the last accepted step per secret atomically, and reject any step less than or equal to it. The verify_totp_code rustdoc shows the complete check.
  • Applied tarpit: LoginGuard::record_login_failure_and_wait records a failure and awaits its progressive delay; jail state is bounded and local to the process. Concurrent admission shares the configured identity ceiling. At capacity, a new identity evicts the least recently failed counter and a new offender evicts the jail that expires soonest, so a flood of unrelated identities cannot stop a later identity from being counted and jailed. It can still age out older counters, so pair the jail with upstream rate limits.
  • Local rate limiter: Fixed-window counters retain at most 16,384 identities with keys up to 256 bytes, reclaim expired identities on subsequent requests, and reject zero budgets or exhausted admission. Clones share state; this is not a distributed limit across application instances. Prefer one RateLimiter per policy. The legacy global is_rate_limited helper keeps a separate budget per (key, max_requests, window), so policies on the same key neither share a count nor reset each other, but they share its capacity. rate_limit_middleware keys the verified socket peer per IPv4 address and per IPv6 /64 (IPv4-mapped IPv6 counts as IPv4), so rotating addresses inside one delegated prefix shares a budget instead of filling the identity table.

๐Ÿ”Ž 7. Bounded Payload, Log & Asset Guards

  • Schema Guard: Rejects malformed JSON, recursive duplicate keys, excessive body size/depth, and ambiguous JSON content types. An application can also compile one bounded JSON Schema 2020-12 document or one explicit OpenAPI 3.1 component into route-scoped middleware. References stay local, pattern matching uses the linear-time regex engine, and schema construction performs no filesystem or network retrieval.
  • Response DLP: mask_response_payload and DlpResponseLayer mask complete PEM private-key blocks (PKCS#8 plain or encrypted, RSA, EC, DSA, OpenSSH and OpenPGP), AWS access-key IDs and postgres/postgresql/mysql/redis URL passwords in bounded textual responses (at most 2 MiB). Every pass is linear in the body length. A URL password is recognized only inside the URL authority: credentials must be percent-encoded, and the authority ends at the first /, ?, #, whitespace, quote, <, >, backtick or control character, or after 2,048 bytes.
  • Log redaction: redact_secrets handles repeated Bearer/assignment, PEM, AWS, and database patterns, including escaped quoted values, in time linear in the record length. An assignment key (password, passwd, secret, api_key, token, authorization, cookie, session) also matches as the final component of a compound name joined by _, - or . (DB_PASSWORD, access_token, client-secret, app.db.password) or when a final key/id component follows it (SECRET_KEY, session_id). An unquoted Authorization/Proxy-Authorization or Cookie/Set-Cookie value is redacted to the end of its line, so later cookies and credentials containing spaces are covered; only a recognized authentication scheme such as Bearer, Basic, Digest or Token is kept. Records over 64 KiB are replaced wholesale by an oversized-record marker. The host must invoke it before emitting untrusted log fields; pattern matching is not a guarantee that arbitrary sensitive content can be recognized.
  • SRI: Generate escaped SHA-384 tags from bytes or bounded local JS/CSS files with sri_script_tag_from_file and sri_link_tag_from_file.

๐Ÿงฉ 8. Deterministic Threat Sentinel

  • Explainable assessment: Classifies caller-supplied aggregate windows against explicit credential-stuffing, API-scraping and distributed-automation thresholds; it does not claim AI attribution. SentinelObservation deserialization applies the same validation as try_new, so a zero window, zero requests or inconsistent counts are rejected rather than reaching the classifier.
  • Bounded proof of work: Issues OS-random, HMAC-authenticated, subject-bound challenges with bounded TTL, difficulty and local cardinality.
  • One-shot verification: Exactly one concurrent verifier consumes an active challenge in the current process. Distributed replay state and traffic identity remain application/deployment responsibilities.

๐Ÿ’พ 9. Durable Local SIEM Spool

  • Restart validation: DurableSiemSpool synchronously appends normalized, unsigned LiveSecurityEvent v1 records and validates the whole bounded file when it is reopened.
  • Fail-closed framing: A version header, exact length and SHA-256 digest detect truncation and accidental modification; byte and record ceilings stop unbounded growth.
  • Explicit boundary: This is a single-process local spool. SHA-256 is not source authentication, and the application still owns trusted directories, permissions, rotation, retention, backup, delivery, retry, acknowledgement, dead-letter policy and any Splunk/Datadog/Elastic/Syslog adapter.

๐Ÿ” 10. Authenticated Local SIEM Journal

  • HMAC chain: AuthenticatedSiemSpool binds every normalized event to its one-based sequence, named key, predecessor tag and exact payload using domain-separated HMAC-SHA256.
  • Explicit rotation: SiemKeyRing writes with one active key and verifies older frames with at most seven historical keys. Secret bytes live in zeroizing storage and are redacted from Debug.
  • Fail-closed recovery: Restart rejects forged content, wrong or absent keys, reordered/removed interior frames, malformed encoding and quota or external-length violations. A trusted external checkpoint is still needed to detect removal of a complete valid tail.

๐Ÿ“ฆ Installation

Add rullst-security to your Cargo.toml:

[dependencies]
rullst-security = "12.1.0"

โšก Quickstart Code Examples

1. Honeypot & CSP Middleware Setup

use axum::{Router, routing::get};
use rullst_security::{HoneypotLayer, HoneypotState, CspSecurityLayer};

#[tokio::main]
async fn main() {
    let state = HoneypotState::default(); // Catches /.env, /admin.php, etc.

    let app = Router::new()
        .route("/api/data", get(|| async { "Protected Data" }))
        .layer(CspSecurityLayer::default())
        .layer(HoneypotLayer::new(state));
}

2. XSS HTML Sanitization

use rullst_security::HtmlSanitizer;

let dirty_input = "<script>alert('xss')</script><p>Clean Text</p>";
let safe_html = HtmlSanitizer::sanitize(dirty_input);

assert_eq!(safe_html, "<p>Clean Text</p>");

3. Role & Ownership Authorization (RBAC)

use rullst_security::{UserContext, RbacGuard};

let user = UserContext::new("usr_100", vec!["editor".to_string()]);

// Authorize role
let is_allowed = RbacGuard::authorize(&user, "editor");
assert!(is_allowed.is_ok());

// Authorize owner or admin
let resource_owner = "usr_100";
let is_owner = RbacGuard::authorize_owner_or_role(&user, resource_owner, "admin");
assert!(is_owner.is_ok());

4. Cryptographic Audit Log Chain

use std::sync::Arc;
use rullst_security::{AuditChain, StdoutAuditLogger};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let secret = b"my-master-hmac-secret-key-32-bytes";
    let logger = Arc::new(StdoutAuditLogger::default());
    let chain = AuditChain::try_new(secret, logger)?;

    let record = chain
        .record_event("admin_user", "UPDATE_ROLE", "user_456", "{\"role\":\"admin\"}")
        .await?;

    assert!(AuditChain::verify_record(secret, &record));
    Ok(())
}

5. TOTP Enrollment QR

use rullst_security::{build_mfa_qr_svg, try_generate_mfa_secret};

fn enrollment_qr() -> Result<String, rullst_security::SecurityError> {
    let secret = try_generate_mfa_secret()?;
    build_mfa_qr_svg("My Rullst App", "alice@example.com", &secret)
}

Store the secret encrypted, show the QR only during a protected enrollment ceremony, and require a verified code before enabling MFA.

6. Route-scoped JSON Schema enforcement

use axum::{Router, middleware, routing::post};
use rullst_security::{
    JsonSchemaPolicy, SchemaPolicyError, json_schema_guard_middleware,
};
use serde_json::json;

fn schema_routes() -> Result<Router, SchemaPolicyError> {
    let policy = JsonSchemaPolicy::from_schema(json!({
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object",
        "properties": { "name": { "type": "string", "minLength": 1 } },
        "required": ["name"],
        "additionalProperties": false
    }))?;

    Ok(Router::new().route(
        "/users",
        post(|| async { "accepted" }).layer(middleware::from_fn_with_state(
            policy,
            json_schema_guard_middleware,
        )),
    ))
}

The compiled layer returns 415 for unsafe requests with a non-JSON media type, 400 for malformed/duplicate/oversized/deep JSON, and 422 for a valid JSON value that does not match the selected schema. Authentication, authorization, ownership and domain validation remain separate.

7. Opt-in proof-of-work assessment

use rullst_security::{
    ProofOfWorkConfig, SentinelObservation, SentinelPolicy, ThreatSentinel,
};
use std::time::Duration;

fn assess_login_window() -> Result<bool, rullst_security::SentinelError> {
    let sentinel = ThreatSentinel::try_new(
        b"replace-with-at-least-32-high-entropy-secret-bytes",
        SentinelPolicy::default(),
        ProofOfWorkConfig::default(),
    )?;
    let signals = SentinelObservation::try_new(
        Duration::from_secs(60), 25, 20, 8, 3, 1, 0,
    )?;
    Ok(sentinel
        .assess("account-or-device:opaque-id", signals)?
        .challenge()
        .is_some())
}

The host must derive the subject from trusted application state, provide an accessible alternative, limit issuance and explicitly verify the returned token/nonce before admitting the protected operation.

8. Persist a bounded local SIEM event

use rullst_security::{DurableSiemSpool, LiveSecurityEvent, SiemSpoolError};

fn persist_denial() -> Result<u64, SiemSpoolError> {
    let spool = DurableSiemSpool::try_open("var/security-events.spool")?;
    let receipt = spool.append_local(LiveSecurityEvent::local(
        "RBAC_ACCESS_DENIED",
        "owner mismatch",
        "192.0.2.50",
    ))?;
    Ok(receipt.sequence())
}

Create and permission the parent directory before opening the spool, use only one writer process per file, and deliver/rotate it through an application-owned operator. Reopening validates frames but does not authenticate the event source or confirm remote receipt.

9. Persist and verify an authenticated local SIEM event

use rullst_security::{
    AuthenticatedSiemSpool, AuthenticatedSiemSpoolError, LiveSecurityEvent,
    SiemIntegrityKey, SiemKeyRing,
};

fn persist_authenticated() -> Result<(), AuthenticatedSiemSpoolError> {
    let active = SiemIntegrityKey::try_new(
        "security-2026-09",
        b"0123456789abcdef0123456789ABCDEF".to_vec(),
    )?;
    let keys = SiemKeyRing::try_new(active, std::iter::empty())?;
    let spool = AuthenticatedSiemSpool::try_open("var/security-events.auth", keys)?;
    spool.append_local(LiveSecurityEvent::local(
        "RBAC_ACCESS_DENIED",
        "owner mismatch",
        "192.0.2.50",
    ))?;
    let verified = spool.read_verified()?;
    assert!(verified.iter().all(|event| event.verified_hmac));
    Ok(())
}

Generate the key from a cryptographic secret manager rather than using the example literal. During rotation, reopen with the new active key and every historical key referenced by retained frames. This API does not send events to an external SIEM or acknowledge remote receipt.


๐Ÿ“– License

Licensed under the MIT License. Part of the Rullst Monorepo Framework.