自定义规则

codescan 支持通过 JSON 文件定义用户自定义规则。自定义规则使用与内置规则相同的引擎，并与内置规则一起出现在输出中。

加载自定义规则

# 单个文件
codescan --rules-file ./rules/my-rules.json .

# 多个文件
codescan --rules-file ./rules/secrets.json --rules-file ./rules/compliance.json .

也可以在 codescan.toml 中指定：

[rules]
extra_files = ["./rules/internal.json", "./rules/compliance.json"]

JSON 格式

自定义规则文件支持两种格式：

数组格式

[
  {
    "id": "CUSTOM001",
    "category": "CUSTOM",
    "severity": "error",
    "pattern": "(?i)\\binternal_secret\\b",
    "message": "发现内部密钥字符串",
    "help": "提交前请删除此内容"
  }
]

对象格式

{
  "rules": [
    {
      "id": "CUSTOM001",
      "category": "CUSTOM",
      "severity": "error",
      "pattern": "(?i)\\binternal_secret\\b",
      "message": "发现内部密钥字符串",
      "help": "提交前请删除此内容"
    }
  ]
}

规则字段

字段	必填	描述
id	是	唯一规则标识符（例如 COMPANY001）
category	是	类别名称（例如 SECRET、CUSTOM、COMPLIANCE）
severity	是	"error"、"warning" 或 "info"
pattern	是	正则表达式（Rust regex crate 语法）
message	是	人类可读的发现描述
help	否	可选的修复建议

模式语法

模式使用 Rust regex crate，该库保证线性时间复杂度，不支持：

• 前瞻/后顾（(?=...)、(?!...)、(?<=...)、(?<!...)）
• 反向引用（\1）

常用特性

(?i)          大小写不敏感标志
\b            单词边界
(?:...)       非捕获组
[^abc]        否定字符类
\w \d \s      字符类
{3,8}         量词范围

JSON 中的转义

在 JSON 字符串中，反斜杠需要双写：

正则	JSON 字符串
\b	"\\b"
\d+	"\\d+"
\(	"\\("

示例

合规规则

[
  {
    "id": "COMPLIANCE001",
    "category": "COMPLIANCE",
    "severity": "error",
    "pattern": "(?i)\\b(ssn|social.?security.?number)\\b",
    "message": "疑似社会安全号码引用",
    "help": "源代码中不得出现 PII 数据"
  },
  {
    "id": "COMPLIANCE002",
    "category": "COMPLIANCE",
    "severity": "warning",
    "pattern": "(?i)\\b(credit.?card|card.?number|cvv|ccv)\\b",
    "message": "疑似信用卡数据引用",
    "help": "请按照 PCI-DSS 要求处理持卡人数据"
  }
]

组织特定密钥

[
  {
    "id": "ORG001",
    "category": "SECRET",
    "severity": "error",
    "pattern": "ACME_[A-Z0-9_]{16,}",
    "message": "检测到 ACME 内部 Token 模式",
    "help": "请轮换此 Token 并将其存储在密钥库中"
  }
]

基础设施规则

[
  {
    "id": "INFRA010",
    "category": "INFRA",
    "severity": "warning",
    "pattern": "(?i)10\\.internal\\.corp",
    "message": "内部主机名被硬编码",
    "help": "请使用服务发现或环境变量"
  }
]

列出所有规则

查看所有内置和自定义规则：

codescan --list-rules
codescan --list-rules --rules-file ./my-rules.json

覆盖内置严重性

自定义规则无法直接覆盖内置规则严重性，但可以使用 codescan.toml：

[rules.severity_overrides]
CUSTOM001 = "warning"