NexusFang-tech/portcullis

# Portcullis 一个用于 git 仓库和本地文件树的密钥与凭据扫描器。 Portcullis 可以检测源代码中的硬编码密钥、API 密钥、私钥以及其他敏感凭据——无论是在工作树中还是埋藏在 git 历史记录中。 ## 安装 ``` # 以开发模式克隆并安装 git clone https://github.com/yourorg/portcullis.git cd portcullis pip install -e ".[dev]" ``` 需要 Python 3.10 或更高版本。 ## 快速开始 ``` # 扫描当前目录 portcullis scan # 扫描特定路径并输出 JSON portcullis scan --path ./my-project --format json # 审计所有提交中的 git 历史记录以查找 secrets portcullis audit --path ./my-repo # 按严重程度过滤 portcullis scan --severity critical --format csv ``` ## 用法 ### `scan` — 扫描文件中的密钥 ``` portcullis scan [OPTIONS] ``` | 选项 | 描述 | |---|---| | `--path PATH` | 要扫描的目录（默认：`.`） | | `--depth N` | 最大目录深度 | | `--exclude PATTERN [...]` | 要排除的 Glob 模式 | | `--severity LEVEL` | 最低严重级别：`critical`、`high`、`medium`、`low` | | `--format FORMAT` | 输出格式：`table`（默认）、`json`、`csv` | 示例： ``` # 排除 vendor 目录和压缩文件 portcullis scan --exclude vendor "*.min.js" # 浅层扫描，仅限 critical portcullis scan --depth 2 --severity critical # 用于 CI 集成的 JSON 输出 portcullis scan --format json > results.json ``` ### `audit` — 扫描 git 提交历史 ``` portcullis audit [OPTIONS] ``` | 选项 | 描述 | |---|---| | `--path PATH` | git 仓库的路径（默认：`.`） | | `--max-commits N` | 限制要扫描的提交数量 | | `--severity LEVEL` | 报告的最低严重级别 | | `--format FORMAT` | 输出格式：`table`、`json`、`csv` | audit 命令会遍历仓库中的每一个提交，并扫描每一个文件 blob。它会对发现结果进行去重，因此对于在多个提交中未更改的文件里的相同密钥，只会报告一次。 ``` # 完整历史审计 portcullis audit # 仅扫描最近 100 次提交 portcullis audit --max-commits 100 --format json ``` ## 配置 在你的项目根目录下创建一个 `.portcullis.yml` 文件： ``` # 从扫描中排除的路径 exclude: - vendor - "*.min.js" - test/fixtures # 报告的最低严重程度 severity: medium # 最大目录深度 max_depth: 10 # 额外的规则文件 custom_rules: - rules/company-rules.yml ``` CLI 参数会覆盖配置文件中的值。 ## 检测引擎 Portcullis 使用多层检测方法： 1. **正则表达式模式匹配** — 每条规则定义了一个针对已知凭据格式的正则表达式 2. **Shannon 熵分析** — 对匹配的字符串进行随机性评估；低熵匹配（如占位符值）会被过滤掉 3. **误报过滤器** — 针对每条规则的正则过滤器会消除已知的示例/占位符值 ### 内置规则 | 规则 ID | 目标 | 严重级别 | |---|---|---| | `aws-access-key` | AWS Access Key IDs (AKIA...) | Critical | | `aws-secret-key` | AWS Secret Access Keys | Critical | | `github-pat` | GitHub Personal Access Tokens | Critical | | `private-key-pem` | PEM-encoded private keys | Critical | | `stripe-secret-key` | Stripe API secret keys | Critical | | `slack-bot-token` | Slack bot tokens | Critical | | `jwt-token` | JSON Web Tokens | High | | `slack-webhook` | Slack webhook URLs | High | | `database-url` | Database connection strings | High | | `password-in-config` | 配置文件中的密码 | High | | `google-api-key` | Google Cloud API keys | High | | `generic-api-key` | 通用 API 密钥模式 | Medium | | `generic-secret` | 通用密钥赋值 | Medium | | ...以及更多 | | | ## 规则编写指南 规则在 YAML 文件中定义。每条规则包含： ``` rules: - id: my-company-token # Unique identifier name: My Company API Token # Human-readable name severity: high # critical, high, medium, low description: > # Optional description Detects My Company API tokens which start with "mc_". pattern: 'mc_[A-Za-z0-9]{32}' # Regex pattern entropy_threshold: 3.5 # Optional: minimum Shannon entropy false_positive_filters: # Optional: regexes that indicate false positives - 'mc_example_token' - 'mc_0{32}' ``` ### 字段 | 字段 | 必填 | 描述 | |---|---|---| | `id` | 是 | 唯一规则标识符 | | `name` | 是 | 显示名称 | | `severity` | 是 | `critical`、`high`、`medium` 或 `low` | | `pattern` | 是 | Python 正则表达式。使用捕获组 `()` 包裹密钥值，以便进行熵分析和脱敏 | | `description` | 否 | 解释该规则检测的内容 | | `entropy_threshold` | 否 | 如果设置，低于此熵值的匹配字符串将被过滤。十六进制使用 ~3.0，base64 使用 ~4.0，混合字母数字使用 ~4.5 | | `false_positive_filters` | 否 | 正则表达式列表；如果任何一个匹配捕获的文本，该发现将被抑制 | ### 提示 - **使用捕获组** — 用 `()` 包裹实际的密钥，以便熵分析针对凭据本身，而不是周围的语法 - **为通用模式设置熵阈值**，以避免标记 `password = "changeme"` - **添加误报过滤器**，用于文档中已知的示例值 - 将自定义规则文件放置在任何位置，并在 `.portcullis.yml` 中引用它们 ## 输出格式 ### 表格（默认） 丰富的终端输出，包含颜色编码的严重级别、文件路径、行号、规则名称和脱敏预览。永远不会打印完整的密钥。 ### JSON ``` { "findings": [ { "rule_id": "aws-access-key", "rule_name": "AWS Access Key ID", "severity": "critical", "file_path": "config/prod.env", "line_number": 3, "redacted_preview": "AKI*****************QA" } ], "total": 1 } ``` ### CSV 标准 CSV，包含表头：`rule_id`、`rule_name`、`severity`、`file_path`、`line_number`、`redacted_preview`、`commit_sha`、`commit_message`、`commit_author`。 ## CI 集成 退出代码 `0` 表示未发现密钥；`1` 表示检测到发现结果。在 CI 流水线中使用： ``` # GitHub Actions - name: Scan for secrets run: portcullis scan --format json --severity high ``` 请参阅 `.github/workflows/ci.yml` 了解项目自身的 CI 配置，该配置使用 ruff linting 在 Python 3.10、3.11 和 3.12 上运行测试。 ## 开发 ``` pip install -e ".[dev]" pytest -v ruff check src/ tests/ ``` ## 许可证 [MIT](LICENSE)

标签：API 密钥, CI/CD 集成, DevSecOps, Git 安全, Java RMI, Linux安全, Python 工具, Redis利用, 上游代理, 仓库审计, 凭据管理, 安全扫描, 对抗攻击, 指令劫持, 敏感信息检测, 数据泄露防护, 时序注入, 版本控制安全, 硬编码密钥, 私有密钥检测, 网络探测, 逆向工具, 防御框架