codescan

中文

English

中文

English

外观

抑制规则 ​

codescan 支持两种抑制机制：源文件中的内联注释和 codescan.toml 中的配置文件条目。

内联抑制 ​

内联抑制与语言无关——无论注释语法如何（//、#、--、/* */ 等），都会扫描原始注释文本。

抑制下一行 ​

将指令放在发现之前的那一行：

python
# codescan:ignore-next-line SECRET001
password = "hunter2"
javascript
// codescan:ignore-next-line:SECRET001
const password = "hunter2";

空格分隔形式（codescan:ignore-next-line SECRET001）和冒号分隔形式（codescan:ignore-next-line:SECRET001）均被接受。冒号形式适用于注释中空格会引起歧义的语言。

抑制同一行 ​

python
password = os.getenv("DB_PASS", "fallback")  # codescan:ignore SECRET001
javascript
const url = "http://internal.corp";  // codescan:ignore:INFRA004

抑制多个规则 ​

python
result = hashlib.md5(token).hexdigest()  # codescan:ignore CRYPTO001,ENTROPY001

抑制某行的所有规则 ​

python
secret = "..."  # codescan:ignore

块抑制 ​

python
# codescan:ignore-start SECRET001,SECRET002
TEST_PASSWORD = "test123"
TEST_API_KEY = "sk-test-aaabbbccc"
# codescan:ignore-end

块抑制从 ignore-start（不含该行）开始，到 ignore-end（不含该行）结束。起止行本身不被抑制。

添加原因注释 ​

可以添加 reason: 注释作为文档说明——它会被解析但不影响抑制逻辑：

javascript
// codescan:ignore-next-line:SECRET001 reason:test-fixture
const password = "test_only";

各语言示例 ​

所有注释风格均适用：

sql
-- codescan:ignore-next-line:INFRA001
INSERT INTO config VALUES ('db_host', '192.168.1.10');
bash
# codescan:ignore-next-line CRYPTO001
openssl dgst -md5 file.bin
html
<!-- codescan:ignore SECRET001 -->
<input type="hidden" value="...">
rust
/* codescan:ignore EXPLOIT001 */
let query = format!("SELECT * FROM users WHERE id = {}", id);

配置文件抑制 ​

配置文件抑制在 codescan.toml 中定义为 [[suppress]] 条目。它比内联抑制更强大，适用于整个文件、目录范围或类别级别的抑制。

按精确文件路径 ​

toml
[[suppress]]
file = "src/tests/fixtures/db_seed.sql"
rules = ["SECRET001", "INFRA001"]
reason = "测试固件数据"

file 字段支持精确相对路径和路径后缀匹配（例如 "src/auth.py" 匹配 .../src/auth.py）。

按 Glob 模式 ​

toml
[[suppress]]
glob = "**/*.test.ts"
categories = ["SECRET"]
reason = "单元测试可能使用虚假凭证"

按行号 ​

toml
[[suppress]]
file = "config/defaults.py"
line = 42
rules = ["SECRET001"]
reason = "默认占位符，运行时会覆盖"

按类别 ​

toml
[[suppress]]
glob = "legacy/**"
categories = ["CRYPTO", "EXPLOIT"]

按严重性上限 ​

抑制不超过指定严重性的发现：

toml
[[suppress]]
glob = "docs/**"
max_severity = "warning"
reason = "文档示例仅作说明用途"

抑制所有规则 ​

使用 rules = ["*"] 或省略 rules 以抑制所有规则：

toml
[[suppress]]
file = "generated/schema.pb.go"
rules = ["*"]
reason = "自动生成的文件"

组合条件 ​

所有指定条件必须同时满足（AND 逻辑）。若同时提供 rules 和 categories，发现满足任意一个即匹配（OR 逻辑）：

toml
[[suppress]]
glob = "src/internal/**"
rules = ["SECRET001"]
categories = ["INFRA"]

查看被抑制的发现 ​

被抑制的发现默认隐藏。使用以下命令查看：

bash
codescan --show-suppressed .

或在 codescan.toml 中设置 show_suppressed = true。被抑制的发现会显示额外的 = suppressed: <原因> 注释行。

退出码行为 ​

被抑制的发现不计入 --fail-on 退出码。只有活跃（未被抑制）的发现才会导致非零退出。