fix(scanner): reduce false positives in docstrings and inline code#26
Merged
fix(scanner): reduce false positives in docstrings and inline code#26
Conversation
added 2 commits
April 19, 2026 15:23
Add `normalize::python_docstring_mask()` that returns, for each original line of a source file, whether that line sits fully inside a `"""..."""` or `'''...'''` block. `script_analyzer` consults it on `.py` files and files with a python shebang, and suppresses WARN/DANGER findings whose line falls inside a docstring. BLOCK-level rules continue to fire in docstrings. Eliminates false positives like SC-003 / SC-007 triggering on mentions of `rm -rf` or `>/path` inside module docstrings that describe the script's behaviour. Shell heredocs are intentionally not masked -- their body is real executable code.
For WARN-level MD rules, match against a variant of each line where backtick-delimited inline code spans have been blanked to spaces. This eliminates the common false positive where SKILL.md prose references a dangerous command name in backticks (e.g. "behaves differently than `rm -rf` would") and trips MD-004. DANGER/BLOCK rules still match the original text, so wrapping a prompt-injection phrase in backticks cannot be used as an evasion. Also document both scanner false-positive filters (Python docstrings and markdown inline code) in CLAUDE.md conventions.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Cut two well-understood scanner false-positive classes without weakening BLOCK-level detection.
normalize::python_docstring_mask):script_analyzernow skips WARN/DANGER findings whose original line sits fully inside a"""..."""/'''...'''block in.pyfiles and python-shebang scripts. BLOCK rules still fire. Removes common SC-003 / SC-007 noise from module docstrings describing tool behaviour (e.g. "behaves likerm -rf", "written to<workdir>/out.json").strip_inline_code): WARN-level MD rules now match against a variant of each line with backtick spans blanked to spaces; DANGER/BLOCK still match original text so backtick wrapping is not an evasion. Removes MD-004 firing on prose that references command names inline.Scope is intentionally narrow: shell heredocs remain scanned (their body is executable), SC-002 hits like
subprocess.run/re.compilestill fire (they are real API calls), gate still mediates user decision.Impact
Measured against the public skillx-run/mac-space-cleanup skill: 18 → 14 findings, exactly the four docstring / inline-code false positives eliminated; the remaining 14 DANGER hits are real API usages left for the gate.
CLAUDE.mdupdated with the two new conventions.Test plan
cargo test --workspace(266 + 124 + … all green)cargo clippy --workspace --all-targets -- -D warningscargo fmt --check#comment semantics, so"""appearing inside a#comment can still flip the state machine. Tracked as follow-up — happy to add a#-stop in a follow-up commit if we want to close that gap here.🤖 Generated with Claude Code