security-ownership-map

安全所有权映射

概述

根据 git 历史构建人员与文件的二分图，然后计算所有权风险，并导出用于 Neo4j/Gephi 的图数据文件。同时构建文件共变更图（基于共享提交的 Jaccard 相似度），按文件共同变更的情况聚类，同时忽略大型、嘈杂的提交。

要求

• Python 3
• networkx（必需；默认启用社区检测）

使用以下命令安装：

pip install networkx

工作流

1. 确定仓库范围和时间窗口（可选 --since/--until）。
2. 确定敏感度规则（使用默认规则或提供 CSV 配置）。
3. 使用 scripts/run_ownership_map.py 构建所有权映射（默认启用共变更图；使用 --cochange-max-files 忽略超节点提交）。
4. 默认计算社区；GraphML 输出为可选项（--graphml）。
5. 使用 scripts/query_ownership.py 查询输出，获取有界 JSON 片段。
6. 持久化并可视化（参见 references/neo4j-import.md）。

默认情况下，共变更图会忽略常见的“胶水”文件（锁文件、.github/*、编辑器配置），以便聚类反映实际代码变更，而非共享基础设施编辑。使用 --cochange-exclude 或 --no-default-cochange-excludes 可覆盖此设置。默认排除 Dependabot 提交；使用 --no-default-author-excludes 可覆盖此设置，或通过 --author-exclude-regex 添加模式。

如果要从共变更聚类中排除 Kbuild 等 Linux 构建胶水文件，请传入：

python skills/skills/security-ownership-map/scripts/run_ownership_map.py \
  --repo /path/to/linux \
  --out ownership-map-out \
  --cochange-exclude "**/Kbuild"

快速入门

在仓库根目录运行：

python skills/skills/security-ownership-map/scripts/run_ownership_map.py \
  --repo . \
  --out ownership-map-out \
  --since "12 months ago" \
  --emit-commits

默认设置：排除作者身份、作者日期和合并提交。如有需要，可使用 --identity committer、--date-field committer 或 --include-merges。

示例（覆盖共变更排除项）：

python skills/skills/security-ownership-map/scripts/run_ownership_map.py \
  --repo . \
  --out ownership-map-out \
  --cochange-exclude "**/Cargo.lock" \
  --cochange-exclude "**/.github/**" \
  --no-default-cochange-excludes

默认计算社区。要禁用：

python skills/skills/security-ownership-map/scripts/run_ownership_map.py \
  --repo . \
  --out ownership-map-out \
  --no-communities

敏感度规则

默认情况下，脚本会标记常见的身份验证、加密和密钥路径。提供 CSV 文件可覆盖此设置：

# pattern,tag,weight
**/auth/**,auth,1.0
**/crypto/**,crypto,1.0
**/*.pem,secrets,1.0

使用 --sensitive-config path/to/sensitive.csv 指定该文件。

输出数据文件

ownership-map-out/ 包含：

• people.csv（节点：人员）
• files.csv（节点：文件）
• edges.csv（边：触及）
• cochange_edges.csv（文件间共变更边，带有 Jaccard 权重；使用 --no-cochange 时不生成）
• summary.json（安全所有权发现结果）
• commits.jsonl（可选，使用 --emit-commits 时生成）
• communities.json（默认根据可用的共变更边计算；包含每个社区的 maintainers；使用 --no-communities 可禁用）
• cochange.graph.json（NetworkX node-link JSON，包含 community_id 和 community_maintainers；如果没有共变更边，则回退到 ownership.graph.json）
• ownership.graphml / cochange.graphml（可选，使用 --graphml 时生成）

people.csv 根据作者提交偏移量进行时区检测，包含 primary_tz_offset、primary_tz_minutes 和 timezone_offsets。

大模型查询辅助工具

使用 scripts/query_ownership.py 返回较小且 JSON 大小受限的片段，避免将完整图加载到上下文中。

示例：

python skills/skills/security-ownership-map/scripts/query_ownership.py --data-dir ownership-map-out people --limit 10
python skills/skills/security-ownership-map/scripts/query_ownership.py --data-dir ownership-map-out files --tag auth --bus-factor-max 1
python skills/skills/security-ownership-map/scripts/query_ownership.py --data-dir ownership-map-out person --person alice@corp --limit 10
python skills/skills/security-ownership-map/scripts/query_ownership.py --data-dir ownership-map-out file --file crypto/tls
python skills/skills/security-ownership-map/scripts/query_ownership.py --data-dir ownership-map-out cochange --file crypto/tls --limit 10
python skills/skills/security-ownership-map/scripts/query_ownership.py --data-dir ownership-map-out summary --section orphaned_sensitive_code
python skills/skills/security-ownership-map/scripts/query_ownership.py --data-dir ownership-map-out community --id 3

使用 --community-top-owners 5（默认值）控制每个社区存储的维护者数量。

基本安全查询

运行以下命令，以有界输出回答常见的安全所有权问题：

# Orphaned sensitive code (stale + low bus factor)
python skills/skills/security-ownership-map/scripts/query_ownership.py --data-dir ownership-map-out summary --section orphaned_sensitive_code

# Hidden owners for sensitive tags
python skills/skills/security-ownership-map/scripts/query_ownership.py --data-dir ownership-map-out summary --section hidden_owners

# Sensitive hotspots with low bus factor
python skills/skills/security-ownership-map/scripts/query_ownership.py --data-dir ownership-map-out summary --section bus_factor_hotspots

# Auth/crypto files with bus factor <= 1
python skills/skills/security-ownership-map/scripts/query_ownership.py --data-dir ownership-map-out files --tag auth --bus-factor-max 1
python skills/skills/security-ownership-map/scripts/query_ownership.py --data-dir ownership-map-out files --tag crypto --bus-factor-max 1

# Who is touching sensitive code the most
python skills/skills/security-ownership-map/scripts/query_ownership.py --data-dir ownership-map-out people --sort sensitive_touches --limit 10

# Co-change neighbors (cluster hints for ownership drift)
python skills/skills/security-ownership-map/scripts/query_ownership.py --data-dir ownership-map-out cochange --file path/to/file --min-jaccard 0.05 --limit 20

# Community maintainers (for a cluster)
python skills/skills/security-ownership-map/scripts/query_ownership.py --data-dir ownership-map-out community --id 3

# Monthly maintainers for the community containing a file
python skills/skills/security-ownership-map/scripts/community_maintainers.py \
  --data-dir ownership-map-out \
  --file network/card.c \
  --since 2025-01-01 \
  --top 5

# Quarterly buckets instead of monthly
python skills/skills/security-ownership-map/scripts/community_maintainers.py \
  --data-dir ownership-map-out \
  --file network/card.c \
  --since 2025-01-01 \
  --bucket quarter \
  --top 5

注意：

• 触及次数默认按作者的提交数计算（而非按文件计算）。使用 --touch-mode file 可按文件计算触及次数。
• 使用 --window-days 90 或 --weight recency --half-life-days 180 平滑变更频率。
• 使用 --ignore-author-regex '(bot|dependabot)' 过滤机器人。
• 使用 --min-share 0.1 仅显示稳定维护者。
• 使用 --bucket quarter 按日历季度分组。
• 使用 --identity committer 或 --date-field committer 切换为提交者归属。
• 使用 --include-merges 纳入合并提交（默认排除）。

摘要格式（默认）

使用此结构，并根据需要添加字段：

{
  "orphaned_sensitive_code": [
    {
      "path": "crypto/tls/handshake.rs",
      "last_security_touch": "2023-03-12T18:10:04+00:00",
      "bus_factor": 1
    }
  ],
  "hidden_owners": [
    {
      "person": "alice@corp",
      "controls": "63% of auth code"
    }
  ]
}

图持久化

需要将 CSV 文件加载到 Neo4j 时，请参阅 references/neo4j-import.md。其中包含约束、导入 Cypher 语句和可视化建议。

备注

• summary.json 中的 bus_factor_hotspots 列出公交因子较低的敏感文件；orphaned_sensitive_code 是其中已过时的子集。
• 如果 git log 过大，可使用 --since 或 --until 缩小范围。
• 将 summary.json 与 CODEOWNERS 进行比较，以突出显示所有权偏差。