zz-code-recon

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CodeRecon - Deep Architectural Context Building

CodeRecon - 深度架构上下文构建

Build comprehensive architectural understanding through ultra-granular code analysis. Designed for security auditors, code reviewers, and developers who need to rapidly understand unfamiliar codebases before diving deep.

通过超精细的代码分析建立全面的架构认知。专为需要在深入研究前快速了解陌生代码库的安全审计人员、代码审查人员和开发者设计。

Overview

概述

CodeRecon is a systematic approach to codebase reconnaissance that builds layered understanding from high-level architecture down to implementation details. Inspired by Trail of Bits' audit-context-building methodology.

CodeRecon是一种系统化的代码库侦察方法，能够从高层架构到实现细节逐层构建认知。灵感来源于Trail of Bits的审计上下文构建方法论。

Why CodeRecon?

为什么选择CodeRecon？

Before you can find vulnerabilities, you need to understand:

How the system is architected
Where data flows
What the trust boundaries are
Where security-critical logic lives

This skill provides a structured methodology for building that context efficiently.

在发现漏洞之前，你需要先了解：

系统的架构方式
数据流的走向
信任边界的位置
安全关键逻辑的所在

本方法提供了一套结构化的方法论，可高效构建上述上下文。

The Recon Pyramid

侦察金字塔

                    ┌─────────────┐
                    │   DETAILS   │  ← Implementation specifics
                   ─┼─────────────┼─
                  / │  FUNCTIONS  │  ← Key function analysis
                 /  ─┼─────────────┼─
                /   │   MODULES   │  ← Component relationships
               /    ─┼─────────────┼─
              /     │ ARCHITECTURE│  ← System structure
             /      ─┼─────────────┼─
            /       │   OVERVIEW  │  ← High-level understanding
           ─────────┴─────────────┴─────────

Start broad, go deep systematically.

                    ┌─────────────┐
                    │   DETAILS   │  ← 实现细节
                   ─┼─────────────┼─
                  / │  FUNCTIONS  │  ← 关键函数分析
                 /  ─┼─────────────┼─
                /   │   MODULES   │  ← 组件关系
               /    ─┼─────────────┼─
              /     │ ARCHITECTURE│  ← 系统结构
             /      ─┼─────────────┼─
            /       │   OVERVIEW  │  ← 高层认知
           ─────────┴─────────────┴─────────

从宽泛入手，系统性地深入细节。

Phase 1: Overview Reconnaissance

第一阶段：概览侦察

1.1 Project Identification

1.1 项目识别

Gather basic project information:

bash

undefined

收集基础项目信息：

bash

undefined

Check for documentation

检查文档

ls -la README* ARCHITECTURE* SECURITY* CHANGELOG* docs/

Identify build system

识别构建系统

ls package.json Cargo.toml go.mod pyproject.toml Makefile

Check for tests

检查测试文件

ls -la test* spec* _test tests/

Identify CI/CD

识别CI/CD配置

ls -la .github/workflows/ .gitlab-ci.yml Jenkinsfile .circleci/

undefined

ls -la .github/workflows/ .gitlab-ci.yml Jenkinsfile .circleci/

undefined

1.2 Technology Stack Detection

1.2 技术栈检测

bash

undefined

bash

undefined

Language distribution

语言分布统计

Framework indicators

框架识别

undefined

undefined

1.3 Dependency Analysis

1.3 依赖分析

bash

undefined

bash

undefined

Python dependencies

Python依赖

cat requirements.txt pyproject.toml setup.py 2>/dev/null | grep -E "^\s*[a-zA-Z]"

Node.js dependencies

Node.js依赖

cat package.json | jq '.dependencies, .devDependencies'

Rust dependencies

Rust依赖

cat Cargo.toml | grep -A 100 "[dependencies]"

Go dependencies

Go依赖

cat go.mod | grep -E "^\s+[a-z]"

undefined

cat go.mod | grep -E "^\s+[a-z]"

undefined

1.4 Create Technology Map

1.4 绘制技术栈图谱

markdown

undefined

markdown

undefined

Technology Map: [PROJECT NAME]

技术栈图谱: [项目名称]

Languages

编程语言

Language	Files	Lines	Primary Use
Python	150	25K	Backend API
TypeScript	80	12K	Frontend
Solidity	12	2K	Smart Contracts

语言	文件数	代码行数	主要用途
Python	150	25K	后端API
TypeScript	80	12K	前端
Solidity	12	2K	智能合约

Key Dependencies

核心依赖

Package	Version	Purpose	Security Notes
fastapi	0.100.0	Web framework	Recent CVEs: None
web3.py	6.0.0	Blockchain client	Check signing
pyjwt	2.8.0	JWT handling	Verify alg checks

包	版本	用途	安全说明
fastapi	0.100.0	Web框架	近期CVE：无
web3.py	6.0.0	区块链客户端	需检查签名逻辑
pyjwt	2.8.0	JWT处理	需验证算法校验

Infrastructure

基础设施

Database: PostgreSQL 15
Cache: Redis 7
Message Queue: RabbitMQ
Container: Docker + K8s

undefined

数据库: PostgreSQL 15
缓存: Redis 7
消息队列: RabbitMQ
容器化: Docker + K8s

undefined

Phase 2: Architecture Mapping

第二阶段：架构映射

2.1 Directory Structure Analysis

2.1 目录结构分析

bash

undefined

bash

undefined

Top-level structure

顶层目录结构

tree -L 2 -d

Identify entry points

识别入口文件

find . -name "main.py" -o -name "app.py" -o -name "index.ts" -o -name "main.go"

Identify config

识别配置文件

find . -name "config*" -o -name "settings*" -o -name ".env*"

undefined

find . -name "config*" -o -name "settings*" -o -name ".env*"

undefined

2.2 Component Identification

2.2 组件识别

Look for common patterns:

project/
├── api/           # HTTP endpoints
├── auth/          # Authentication
├── core/          # Business logic
├── db/            # Database layer
├── models/        # Data models
├── services/      # External services
├── utils/         # Utilities
├── workers/       # Background jobs
└── tests/         # Test suite

寻找常见的目录模式：

project/
├── api/           # HTTP端点
├── auth/          # 认证模块
├── core/          # 业务逻辑
├── db/            # 数据库层
├── models/        # 数据模型
├── services/      # 外部服务集成
├── utils/         # 工具函数
├── workers/       # 后台任务
└── tests/         # 测试套件

2.3 Create Architecture Diagram

2.3 绘制架构图

┌─────────────────────────────────────────────────────────────┐
│                        CLIENTS                              │
│              (Web, Mobile, API Consumers)                   │
└─────────────────────────┬───────────────────────────────────┘
                          │ HTTPS
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                      API GATEWAY                            │
│                   (Rate Limiting, Auth)                     │
└─────────────────────────┬───────────────────────────────────┘
                          │
          ┌───────────────┼───────────────┐
          ▼               ▼               ▼
    ┌──────────┐   ┌──────────┐   ┌──────────┐
    │  Auth    │   │  Core    │   │  Admin   │
    │ Service  │   │  API     │   │  API     │
    └────┬─────┘   └────┬─────┘   └────┬─────┘
         │              │              │
         └──────────────┼──────────────┘
                        │
          ┌─────────────┼─────────────┐
          ▼             ▼             ▼
    ┌──────────┐  ┌──────────┐  ┌──────────┐
    │ Database │  │  Cache   │  │ External │
    │ (Postgres)│  │ (Redis)  │  │  APIs    │
    └──────────┘  └──────────┘  └──────────┘

┌─────────────────────────────────────────────────────────────┐
│                        客户端                              │
│              (Web、移动端、API消费者)                   │
└─────────────────────────┬───────────────────────────────────┘
                          │ HTTPS
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                      API网关                            │
│                   (限流、认证)                     │
└─────────────────────────┬───────────────────────────────────┘
                          │
          ┌───────────────┼───────────────┐
          ▼               ▼               ▼
    ┌──────────┐   ┌──────────┐   ┌──────────┐
    │  认证服务 │   │  核心API │   │  管理API │
    │          │   │          │   │          │
    └────┬─────┘   └────┬─────┘   └────┬─────┘
         │              │              │
         └──────────────┼──────────────┘
                        │
          ┌─────────────┼─────────────┐
          ▼             ▼             ▼
    ┌──────────┐  ┌──────────┐  ┌──────────┐
    │ 数据库 │  │  缓存   │  │  外部API │
    │ (Postgres)│  │ (Redis)  │  │          │
    └──────────┘  └──────────┘  └──────────┘

2.4 Trust Boundary Identification

2.4 信任边界识别

Map where trust levels change:

markdown

undefined

标记信任级别变化的位置：

markdown

undefined

Trust Boundaries

信任边界

Boundary 1: Internet → API Gateway

边界1：互联网 → API网关

Type: Network boundary
Controls: TLS, Rate limiting, WAF
Risks: DDoS, Injection, Auth bypass

类型: 网络边界
控制措施: TLS、限流、WAF
风险: DDoS攻击、注入攻击、认证绕过

Boundary 2: API Gateway → Services

边界2：API网关 → 服务

Type: Authentication boundary
Controls: JWT validation, Role checks
Risks: Token forgery, Privilege escalation

类型: 认证边界
控制措施: JWT验证、角色校验
风险: 令牌伪造、权限提升

Boundary 3: Services → Database

边界3：服务 → 数据库

Type: Data access boundary
Controls: Query parameterization, Connection pooling
Risks: SQL injection, Data leakage

类型: 数据访问边界
控制措施: 查询参数化、连接池
风险: SQL注入、数据泄露

Boundary 4: Services → External APIs

边界4：服务 → 外部API

Type: Third-party integration
Controls: API keys, Request signing
Risks: SSRF, Secret exposure

undefined

类型: 第三方集成边界
控制措施: API密钥、请求签名
风险: SSRF攻击、密钥泄露

undefined

Phase 3: Module Deep Dive

第三阶段：模块深入分析

3.1 Entry Point Analysis

3.1 入口点分析

For each entry point type:

python

undefined

针对每种入口点类型：

python

undefined

HTTP Routes - map all endpoints

HTTP路由 - 映射所有端点

CLI Commands

CLI命令

grep -rn "@click.command|argparse|clap" --include=".py" --include=".rs"

Event Handlers

事件处理器

grep -rn "@consumer|@handler|on_message" --include="*.py"

undefined

grep -rn "@consumer|@handler|on_message" --include="*.py"

undefined

3.2 Create Entry Point Map

3.2 绘制入口点图谱

markdown

undefined

markdown

undefined

Entry Points

入口点

HTTP API

Method	Path	Handler	Auth	Input
POST	/api/login	auth.login	None	JSON body
GET	/api/users	users.list	JWT	Query params
POST	/api/transfer	tx.transfer	JWT + 2FA	JSON body
GET	/admin/logs	admin.logs	Admin JWT	Query params

请求方法	路径	处理函数	认证要求	输入
POST	/api/login	auth.login	无	JSON请求体
GET	/api/users	users.list	JWT	查询参数
POST	/api/transfer	tx.transfer	JWT + 双因素认证	JSON请求体
GET	/admin/logs	admin.logs	管理员JWT	查询参数

WebSocket

Event	Handler	Auth	Data
connect	ws.connect	JWT	None
message	ws.message	Session	JSON

事件	处理函数	认证要求	数据
connect	ws.connect	JWT	无
message	ws.message	会话	JSON

Background Jobs

后台任务

Queue	Handler	Trigger	Data Source
emails	email.send	API call	Database
reports	report.gen	Cron	Database

undefined

队列	处理函数	触发方式	数据源
emails	email.send	API调用	数据库
reports	report.gen	定时任务	数据库

undefined

3.3 Data Flow Tracing

3.3 数据流追踪

For each critical endpoint, trace data flow:

POST /api/transfer
       │
       ▼
┌──────────────────┐
│ Request Parser   │ ← Validate JSON schema
│ (validation.py)  │
└────────┬─────────┘
         │ TransferRequest
         ▼
┌──────────────────┐
│ Auth Middleware  │ ← Verify JWT, extract user
│ (middleware.py)  │
└────────┬─────────┘
         │ User context
         ▼
┌──────────────────┐
│ Transfer Service │ ← Business logic
│ (transfer.py)    │
└────────┬─────────┘
         │
    ┌────┴────┐
    ▼         ▼
┌────────┐ ┌────────┐
│ DB     │ │External│
│ Write  │ │ API    │
└────────┘ └────────┘

针对每个关键端点，追踪数据流：

POST /api/transfer
       │
       ▼
┌──────────────────┐
│ 请求解析器   │ ← 验证JSON schema
│ (validation.py)  │
└────────┬─────────┘
         │ TransferRequest
         ▼
┌──────────────────┐
│ 认证中间件  │ ← 验证JWT，提取用户信息
│ (middleware.py)  │
└────────┬─────────┘
         │ 用户上下文
         ▼
┌──────────────────┐
│ 转账服务 │ ← 业务逻辑
│ (transfer.py)    │
└────────┬─────────┘
         │
    ┌────┴────┐
    ▼         ▼
┌────────┐ ┌────────┐
│ 数据库写操作 │ │外部API调用│
│        │ │        │
└────────┘ └────────┘

Phase 4: Function-Level Analysis

第四阶段：函数级分析

4.1 Security-Critical Function Identification

4.1 安全关键函数识别

Search for security-sensitive operations:

bash

undefined

搜索安全敏感操作：

bash

undefined

Authentication

认证相关

grep -rn "def login|def authenticate|def verify_token" --include=".py" grep -rn "function login|authenticate|verifyToken" --include=".ts"

Authorization

授权相关

grep -rn "def is_authorized|def check_permission|@requires_role" --include="*.py"

Cryptography

加密相关

Database

数据库操作

grep -rn "execute|query|cursor" --include=".py" grep -rn ".query|.execute|.raw" --include=".ts"

File Operations

文件操作

grep -rn "open(.)|read|write|unlink" --include=".py"

undefined

grep -rn "open(.)|read|write|unlink" --include=".py"

undefined

4.2 Function Documentation Template

4.2 函数文档模板

For each critical function:

markdown

undefined

针对每个关键函数：

markdown

undefined

Function:

transfer_funds()

函数:

transfer_funds()

Location:

services/transfer.py:45

Purpose: Execute fund transfer between accounts

Parameters:

Name	Type	Source	Validation
from_account	str	JWT claim	UUID format
to_account	str	Request body	UUID format, exists check
amount	Decimal	Request body	> 0, <= balance

Returns: TransferResult

Side Effects:

Writes to
```
transactions
```
table
Calls external payment API
Emits
```
transfer_completed
```
event

Security Considerations:

Requires authenticated user
Rate limited to 10/minute
Amount validated against balance
Audit logged

Potential Risks:

Race condition if concurrent transfers?
What if external API fails mid-transfer?

undefined

位置:

services/transfer.py:45

用途: 执行账户间资金转账

参数:

名称	类型	来源	验证规则
from_account	str	JWT声明	UUID格式校验
to_account	str	请求体	UUID格式校验、账户存在校验
amount	Decimal	请求体	大于0且不超过账户余额

返回值: TransferResult

副作用:

写入
```
transactions
```
表
调用外部支付API
触发
```
transfer_completed
```
事件

安全注意事项:

要求用户已认证
限流为每分钟10次
金额会与账户余额校验
操作会被审计日志记录

潜在风险:

并发转账时是否存在竞态条件？
外部API中途失败会如何处理？

undefined

4.3 Call Graph Analysis

4.3 调用图分析

transfer_funds()
├── validate_request()
│   └── check_uuid_format()
├── get_user_balance()
│   └── db.query()
├── check_rate_limit()
│   └── redis.get()
├── execute_transfer()     ← CRITICAL
│   ├── db.begin_transaction()
│   ├── update_balance()   ← State change
│   ├── external_api.send() ← External call
│   └── db.commit()
└── emit_event()

transfer_funds()
├── validate_request()
│   └── check_uuid_format()
├── get_user_balance()
│   └── db.query()
├── check_rate_limit()
│   └── redis.get()
├── execute_transfer()     ← 关键函数
│   ├── db.begin_transaction()
│   ├── update_balance()   ← 状态变更
│   ├── external_api.send() ← 外部调用
│   └── db.commit()
└── emit_event()

Phase 5: Detail Reconnaissance

第五阶段：细节侦察

5.1 Configuration Analysis

5.1 配置分析

bash

undefined

bash

undefined

Find all config loading

查找所有配置加载逻辑

grep -rn "os.environ|getenv|config." --include=".py" grep -rn "process.env|config." --include=".ts"

Check for hardcoded secrets

检查硬编码密钥

grep -rn "password\s*=|secret\s*=|api_key\s*=" --include="*.py" grep -rn "-----BEGIN|sk-|pk_live_" .

undefined

grep -rn "password\s*=|secret\s*=|api_key\s*=" --include="*.py" grep -rn "-----BEGIN|sk-|pk_live_" .

undefined

5.2 Error Handling Review

5.2 错误处理审查

bash

undefined

bash

undefined

Find exception handling

查找异常处理逻辑

grep -rn "except.:" --include=".py" -A 2 grep -rn "catch\s*(" --include="*.ts" -A 2

Find error responses

查找错误响应

grep -rn "return.*error|raise.Error" --include=".py"

undefined

grep -rn "return.*error|raise.Error" --include=".py"

undefined

5.3 Logging Analysis

5.3 日志分析

bash

undefined

bash

undefined

Find logging statements

查找日志语句

grep -rn "logger.|logging.|console.log" --include=".py" --include=".ts"

Check what's being logged

检查日志中是否包含敏感信息

grep -rn "log.*password|log.*token|log.secret" --include=".py"

undefined

grep -rn "log.*password|log.*token|log.secret" --include=".py"

undefined

Output: Context Document

输出：上下文文档

Template

模板

markdown

undefined

markdown

undefined

[PROJECT NAME] - Security Context Document

[项目名称] - 安全上下文文档

Executive Summary

执行摘要

[2-3 sentences on what this system does]

[2-3句话说明系统功能]

Technology Stack

技术栈

[From Phase 1]

[来自第一阶段的内容]

Architecture

架构

[Diagram from Phase 2]

[来自第二阶段的架构图]

Trust Boundaries

信任边界

[From Phase 2.4]

[来自第二阶段2.4的内容]

Entry Points

入口点

[Table from Phase 3.2]

[来自第三阶段3.2的表格]

Critical Functions

关键函数

[Analysis from Phase 4]

[来自第四阶段的分析]

Data Flows

数据流

[Diagrams from Phase 3.3]

[来自第三阶段3.3的图]

Security Controls

安全控制措施

Control	Implementation	Location	Notes
Authentication	JWT	middleware/auth.py	RS256 signing
Authorization	RBAC	decorators/auth.py	Role-based
Input Validation	Pydantic	schemas/*.py	Type checking
Encryption	AES-256-GCM	utils/crypto.py	At-rest

控制措施	实现方式	位置	说明
认证	JWT	middleware/auth.py	RS256签名
授权	RBAC	decorators/auth.py	基于角色的访问控制
输入验证	Pydantic	schemas/*.py	类型校验
加密	AES-256-GCM	utils/crypto.py	静态数据加密

Areas Requiring Focus

重点关注领域

[High-risk area 1]
[High-risk area 2]
[High-risk area 3]

[高风险领域1]
[高风险领域2]
[高风险领域3]

Open Questions

待解决问题

How is X handled when Y?
What happens if Z fails?

undefined

当Y发生时，X是如何处理的？
如果Z失败会发生什么？

undefined

Quick Start Commands

快速启动命令

bash

undefined

bash

undefined

Full recon script

完整侦察脚本

./scripts/recon.sh /path/to/project

Generate entry point map

生成入口点图谱

./scripts/map-endpoints.sh /path/to/project

Create call graph

生成调用图

./scripts/callgraph.sh /path/to/project

undefined

./scripts/callgraph.sh /path/to/project

undefined

Skill Files

技能文件结构

code-recon/
├── SKILL.md                        # This file
├── resources/
│   ├── recon-checklist.md          # Comprehensive checklist
│   └── question-bank.md            # Questions to answer
├── examples/
│   ├── web-app-recon/              # Web application example
│   └── smart-contract-recon/       # Smart contract example
├── templates/
│   └── context-document.md         # Output template
└── docs/
    └── advanced-techniques.md      # Deep dive techniques

code-recon/
├── SKILL.md                        # 本文件
├── resources/
│   ├── recon-checklist.md          # 完整检查清单
│   └── question-bank.md            # 待解答问题库
├── examples/
│   ├── web-app-recon/              # Web应用侦察示例
│   └── smart-contract-recon/       # 智能合约侦察示例
├── templates/
│   └── context-document.md         # 输出文档模板
└── docs/
    └── advanced-techniques.md      # 进阶技术指南

Guidelines

指导原则

Top-down approach - Start broad, go narrow
Document everything - Your notes are the deliverable
Question assumptions - Verify what docs say vs. what code does
Focus on trust boundaries - That's where bugs live
Time-box phases - Don't get stuck in the weeds early
Iterate - Revisit earlier phases as you learn more

自上而下的方法 - 从宽泛到具体逐步深入
记录所有内容 - 你的笔记就是交付成果
质疑假设 - 验证文档描述与实际代码是否一致
聚焦信任边界 - 漏洞往往出现在这些位置
分阶段限时 - 早期不要陷入细节无法自拔
迭代优化 - 随着认知加深，重新审视之前的阶段

undefined