Skip to content

feat(spider-sense): promote to first-class built-in guard#161

Merged
bb-connor merged 48 commits intomainfrom
feat/ocsf
Mar 4, 2026
Merged

feat(spider-sense): promote to first-class built-in guard#161
bb-connor merged 48 commits intomainfrom
feat/ocsf

Conversation

@bb-connor
Copy link
Copy Markdown
Collaborator

@bb-connor bb-connor commented Mar 4, 2026

Summary

  • Promotes Spider Sense from a feature-gated custom guard (guards.custom with clawdstrike-spider-sense feature) to a first-class built-in guard (chore(deps): bump glob from 10.5.0 to 13.0.0 in /packages/clawdstrike-openclaw #13) with standalone detector classes across all 4 SDKs
  • Extracts a WASM-safe spider_sense detection module (PatternDb, SpiderSenseDetector, cosine similarity) that always compiles
  • Ships built-in spider-sense ruleset and s2bench-v1.json pattern database (36 S2Bench taxonomy entries)
  • Adds SpiderSenseDetector + SpiderSenseGuard in TypeScript (WASM-backed), Python (pure), and Go (pure)
  • Wires spider_sense toggle through adapter core and openclaw adapter

Changes by workstream

Rust core (WS-1):

  • crates/libs/clawdstrike/src/spider_sense.rs — new WASM-safe detection module
  • guards.spider_sense field in GuardConfigs (feature-gated behind full)
  • First-class instantiation in async guard registry; deprecated custom guard fallback with tracing::warn
  • Removed clawdstrike-spider-sense cargo feature
  • rulesets/spider-sense.yaml + rulesets/patterns/s2bench-v1.json

WASM + TypeScript (WS-2):

  • WasmSpiderSenseDetector in hush-wasm/src/detect.rs
  • SpiderSenseDetector class + SpiderSenseGuard in hush-ts

Python (WS-3):

  • Pure Python SpiderSenseDetector + SpiderSenseGuard in hush-py

Go (WS-4):

  • Pure Go SpiderSenseGuard with Screen() + SpiderSenseConfig in hush-go

Adapters + Docs (WS-5):

  • spider_sense toggle in GuardToggles, event types in adapter-core
  • Config defaults, merge logic, validator, engine, loader in openclaw adapter
  • Guard count 12 → 13 in README + CLAUDE.md

Test plan

  • cargo test --workspace — all pass (578+)
  • cargo clippy --workspace -- -D warnings — clean
  • cargo check -p clawdstrike --no-default-features --features policy-event — compiles
  • cargo check -p clawdstrike --no-default-features — compiles (WASM path)
  • cargo check -p hush-wasm — compiles
  • npm test --workspace=packages/sdk/hush-ts — 235 pass
  • Python: 35/35 spider-sense tests pass
  • Go: all package tests pass (18 spider-sense tests)
  • Openclaw adapter: 456 tests pass

🤖 Generated with Claude Code


Note

Medium Risk
Medium risk because it changes policy schema/merging and guard instantiation paths for a security enforcement component, which could alter runtime allow/deny behavior if misconfigured. The changes are fairly contained and add extensive validation/tests, but touch core policy parsing and async guard registry logic.

Overview
Spider-Sense is now a first-class built-in guard configured via guards.spider_sense (with env placeholder resolution and per-guard async config), while the legacy guards.custom clawdstrike-spider-sense path is kept as deprecated and is ignored when the first-class config is enabled.

Adds a new always-compiled, WASM-safe spider_sense detection module (PatternDb + SpiderSenseDetector + fail-closed cosine similarity/screening), exposes it from clawdstrike, and wires it into the async guard implementation; also adds a built-in spider-sense ruleset plus embedded builtin:s2bench-v1 pattern DB.

Extends policy support to schema 1.3.0, adds Spider-Sense-specific deep-merge semantics using YAML field-presence tracking (and a policy-event fallback that preserves spider_sense as raw JSON when full isn’t enabled), and exports new WASM bindings (WasmSpiderSenseDetector). Docs/lockfile are updated to reflect the new guard and ruleset, and versions are bumped to 0.2.2.

Written by Cursor Bugbot for commit 79c13bc. This will update automatically on new commits. Configure here.

…SDKs

Extract Spider Sense from feature-gated custom guard to a first-class
built-in guard with standalone detector classes in Rust, TypeScript,
Python, and Go.

Rust core:
- Extract WASM-safe `spider_sense` detection module (PatternDb,
  SpiderSenseDetector, cosine_similarity_f32, ScreeningResult)
- Add `guards.spider_sense` field to GuardConfigs (feature-gated
  behind `full`)
- Add first-class instantiation in async guard registry with
  deprecated custom guard fallback
- Remove `clawdstrike-spider-sense` cargo feature gate
- Ship built-in `spider-sense` ruleset and `s2bench-v1.json`
  pattern database (36 demo entries)

WASM + TypeScript SDK:
- Add WasmSpiderSenseDetector export in hush-wasm
- Add SpiderSenseDetector class wrapping WASM
- Add SpiderSenseGuard implementing Guard interface

Python SDK:
- Pure Python SpiderSenseDetector and SpiderSenseGuard

Go SDK:
- Pure Go SpiderSenseGuard with Screen() method
- SpiderSenseConfig in policy, wired into engine

Adapters:
- Add spider_sense toggle to GuardToggles and EventType
- Wire through openclaw adapter (config, engine, loader, validator)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Second-pass refinement addressing code review and PR review comments:

Rust core:
- Fix NaN/Inf fail-closed violation in cosine_similarity_f32
- Add non-finite embedding validation in PatternDb::parse_json
- Add deny_unknown_fields to PatternEntry
- Remove duplicated truncate_str utility
- Add placeholder resolution for first-class guard config path
- Add 21 new tests (10 integration, 11 unit)

TypeScript:
- Add try/catch fail-closed in SpiderSenseGuard.check()
- Add 8 edge case tests (dimension mismatch, empty patterns, etc.)

Cross-SDK parity:
- Align deny severity to Error across Python and Go (was Critical)
- Align guard messages to "Spider-Sense" format across all SDKs
- Fix Go config zero-value bug: use pointer types for optional fields

PR review fixes (Bugbot):
- Remove unused Python imports (field, PatternEntry)
- Deduplicate s2bench-v1.json embedding for feedback-evasion

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@bb-connor
Copy link
Copy Markdown
Collaborator Author

@codex

Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6be73393a5

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

- Fix Go/Python cosine similarity NaN/Inf fail-closed (parity with Rust)
- Feature-gate spider-sense ruleset behind `full` in RuleSet (P1)
- Replace Go json.RawMessage with []PatternEntryConfig for YAML compat (P2)
- Make validator accept both boolean and object for spider_sense toggle

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@bb-connor
Copy link
Copy Markdown
Collaborator Author

@codex

Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1fd707ac33

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@bb-connor
Copy link
Copy Markdown
Collaborator Author

Addressed the remaining review findings in commit 7ba0db1e7 and pushed to feat/ocsf.

What was fixed:

  • TS review thread: removed unused local initialization in normalizeTrustedKey (let status: SpiderSenseTrustedKeyStatus;).
  • Rust high-severity thread: added top_k, pattern_db_version, and pattern_db_checksum to SpiderSensePolicyConfig (with defaults/validation), and wired top_k into pattern DB search.
  • CI regressions:
    • fixed clippy::expect-used failures in clawdstrike-policy-event tests
    • regenerated/synced committed hush-wasm Node artifacts (hush_wasm.js, hush_wasm.d.ts, hush_wasm_bg.wasm.d.ts) so WASM sync check passes

Local validation run:

  • cargo test -p clawdstrike --lib policy::tests::test_rulesets_parse_validate_and_match_disk_registry
  • cargo test -p clawdstrike --lib spider_sense
  • cargo clippy -p clawdstrike-policy-event --tests -- -D warnings -D clippy::expect-used
  • cargo test -p clawdstrike-policy-event
  • npm --prefix packages/sdk/hush-ts test -- tests/spider-sense.test.ts tests/spider-sense-conformance.test.ts
  • cd crates/libs/hush-wasm && wasm-pack build --target nodejs --release --out-dir pkg-node with cmp parity checks for committed Node artifacts

@bb-connor
Copy link
Copy Markdown
Collaborator Author

@codex

@bb-connor
Copy link
Copy Markdown
Collaborator Author

Follow-up fixes pushed in 0a3be2fab to address the two remaining Codex review threads:

  1. @clawdstrike/sdk builtin Spider-Sense DB now resolves from package-local assets:

    • packages/sdk/hush-ts/src/guards/patterns/s2bench-v1.json
    • loader path switched to new URL("./patterns/s2bench-v1.json", import.meta.url)
    • build now copies pattern asset into dist via scripts/copy-assets.mjs
  2. OpenClaw canonical translation now preserves executable Spider-Sense config:

    • canonical guards.spider_sense object maps into guards.custom[] package clawdstrike-spider-sense
    • canonical boolean guards.spider_sense: true is now rejected with a load error (fail-fast instead of silent no-op)
    • validator now treats clawdstrike-spider-sense as a reserved package

Validation:

  • npm --prefix packages/sdk/hush-ts run build
  • npm --prefix packages/sdk/hush-ts test -- tests/spider-sense.test.ts tests/spider-sense-conformance.test.ts
  • npm --prefix packages/sdk/hush-ts run typecheck
  • npm --prefix packages/adapters/clawdstrike-openclaw test -- src/policy/loader.test.ts src/policy/validator.test.ts
  • npm --prefix packages/adapters/clawdstrike-openclaw run typecheck

Also resolved both remaining PR review threads in GitHub.

@bb-connor
Copy link
Copy Markdown
Collaborator Author

@codex

@bb-connor
Copy link
Copy Markdown
Collaborator Author

Additional follow-up in 5c2630201:

  • Added explicit sync guards for duplicated S2Bench assets:
    • Go: TestSpiderSenseBuiltinPatternDBMatchesRulesetSource
    • TS: keeps sdk bundled s2bench pattern DB in sync with canonical ruleset source

Also regarding the two hush_wasm.js comments:

  • Those lines are wasm-bindgen generated output.
  • This repo enforces Node WASM artifact parity (wasm-pack ... + cmp) in CI, so manual edits to generated JS are not durable and would fail the sync check.
  • Kept generated output untouched and fixed only source-level code.

Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0a3be2fab2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@bb-connor
Copy link
Copy Markdown
Collaborator Author

Addressed the new review threads and CI failures in dcd34c68b.

What changed:

  • Rust policy now supports schema version 1.3.0 (aligns with TS policy schema support).
  • Spider-Sense first-class config now supports explicit disable override (enabled: false) and async registry skips disabled first-class config without shadowing custom spider-sense guards.
  • Restored pattern DB extensibility by removing deny_unknown_fields from Rust PatternEntry and added a metadata-compat parse test.
  • Fixed SpiderSensePolicyConfig test initializers to include newly required fields (enabled, top_k, pattern_db_version, pattern_db_checksum) so MSRV/coverage/property/offline jobs compile.
  • Restored comprehensive guard examples in docs/src/reference/policy-schema.md full schema example.

Validation run locally:

  • cargo test -p clawdstrike --test spider_sense_guard --no-run
  • cargo test -p clawdstrike --tests --all-features --no-run
  • cargo test --workspace proptest
  • CARGO_NET_OFFLINE=true scripts/cargo-offline.sh test -p clawdstrike --test spider_sense_guard --all-features --no-run
  • cargo +1.93 build --all-targets
  • mdbook build docs

Also resolved the 4 open review threads from Cursor/Codex tied to these issues.

Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e826e7eb18

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Copy link
Copy Markdown

@cursor cursor bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Copy link
Copy Markdown

@cursor cursor bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes and found 2 potential issues.

Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: df29cfb4e3

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Copy link
Copy Markdown

@cursor cursor bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes and found 2 potential issues.

Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Copy link
Copy Markdown

@cursor cursor bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d9c508bf3e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Copy link
Copy Markdown

@cursor cursor bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9e8cc982f5

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Copy link
Copy Markdown

@cursor cursor bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2321a8fb2a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Copy link
Copy Markdown

@cursor cursor bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes and found 2 potential issues.

Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Copy link
Copy Markdown

@cursor cursor bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes and found 2 potential issues.

Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 97be444556

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Copy link
Copy Markdown

@cursor cursor bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Copy link
Copy Markdown

@cursor cursor bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

// No field-presence metadata available: treat as explicit replacement.
// Policy inheritance paths call this intentionally to avoid hidden
// heuristics when source-level field presence is unavailable.
child.clone()
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overly verbose merge implementation duplicates per-field logic

Low Severity

SpiderSensePolicyConfig::merge_with and merge_with_present_fields contain ~300 lines of nearly identical per-field boilerplate for 26 fields. Each field appears in three places: the presence-detection block in merge_with, the conditional assignment in merge_with_present_fields, and the struct definition. Adding a new field requires editing all three locations — a pattern likely to produce silent merge omissions as the config grows.

Fix in Cursor Fix in Web

@bb-connor bb-connor merged commit ae7ed40 into main Mar 4, 2026
7 of 35 checks passed
Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Ok(GuardResult::warn(
self.name(),
"Spider-Sense: LLM response could not be parsed; treating as ambiguous",
)

P1 Badge Honor llm_fail_mode on deep-path parse failures

When the LLM returns non-JSON content, deep_reasoning always emits GuardResult::warn and never checks cfg.llm_fail_mode, so policies configured with llm_fail_mode: deny (fail-closed) silently degrade to warning behavior in exactly the malformed-response scenarios this knob is meant to control.



P2 Badge Apply llm_timeout_ms to deep-path HTTP policy

The HTTP policy used for deep-path LLM calls hard-codes a 30s timeout, so llm_timeout_ms is validated but never actually enforced; users who set short deep-path time budgets will still block on the fixed timeout, which can materially change guard latency and decision timing in production.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

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.

1 participant