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）。
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（包含 community_id + community_maintainers 的 NetworkX 节点链接 JSON；若无协同变更边，则回退到 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 进行比较，以突出显示所有权偏差。