生成审计报告和合规文档
使用 IBM Bob 分析 Galaxium Travels 代码库并生成涵盖代码质量、依赖项健康状况、技术债务和合规态势的结构化审计报告。学习如何从 AI 辅助分析中组装面向利益相关者的文档。
软件审计产生工程团队、安全审查员和合规利益相关者在交付、收购或认证系统之前所依赖的文档证据。
在本教程中,你使用 Bob 系统地分析 Galaxium Travels 代码库并生成五个结构化工件:
- 代码质量摘要: 突出显示整个代码库的可维护性、复杂性和样式问题。
- 依赖项审计: 标记过时、易受攻击或未使用的第三方包。
- 技术债务评估: 编目需要重构的快捷方式、变通方法和区域。
- 合规文档: 记录针对相关监管或组织标准的发现。
- 合并所有发现的综合利益相关者审计报告: 将上述内容整合到一个可共享的文档中。
你构建提示以获得详细的、有证据支持的发现,而不提供补救建议。
在本教程结束时,你将拥有一组审计文档,可以与利益相关者共享并用作补救计划的基准。
在本教程中,Bob 的输出可能会因代码库的当前状态而与示例不同。使用生成的报告作为起点, 并在分发给利益相关者之前完善发现。
你将学习的关键功能
- Context mentions:使用
@符号在提示中引用 特定文件和文件夹。Context mentions 让 Bob 确切知道要分析哪些文件以获得准确的、有证据支持的发现。 - Agent 模式:让 Bob 自主写入文件以将生成的工件 持久化到你的项目中。
- 结构化输出的提示工程: 构建你的提示以包含所需的输出格式,以获得面向利益相关者的文档而不是叙述性散文。
先决条件
设置你的工作区
克隆 Galaxium Travels 仓库
在终端中运行以下命令以克隆 Galaxium Travels 示例仓库:
git clone https://github.com/IBM/galaxium-travels本教程使用仓库的 main 分支,而不是 bob-learning-path-branch。本教程引用的 Java hold
服务和其他组件仅存在于 main 上。
启动 IBM Bob
在你的计算机上启动 IBM Bob IDE。
打开示例项目
在 Bob IDE 中,打开你克隆的 galaxium-travels 文件夹。如果 Bob 询问"你是否信任此文件夹中
文件的作者?",请点击是,我信任作者。
查看根目录中的 README.md 文件以获取应用程序架构的概述。Galaxium Travels 是一个全栈太空
旅行预订系统,具有 Python FastAPI 后端、React/TypeScript 前端和 Java Spring Boot 库存
hold 服务。
打开 Bob 聊天界面
如果聊天界面尚未打开,请点击导航栏中的 Bob 图标或使用快捷键 Option + Command + B (Mac)或 Ctrl + Alt + B(Windows)。
初始化项目上下文
Bob 在启动时默认使用 Agent 模式。如果你更改了模式,请在运行初始化命令之前切换到 Agent 模式。 Bob 需要写入文件以设置项目上下文。本教程使用 Agent 模式的默认功能,而不是按任务限制权限, 因此 Bob 可以在没有额外配置的情况下读写文件。
在聊天界面输入字段中输入 /init 命令。
/init如果禁用了自动批准,Bob 会在读取文件和写入更改之前请求你的许可。在出现这些提示时批准它们——
这适用于 /init 命令以及 Bob 稍后在教程中写入的每个报告。
Bob 读取项目中的相关文件并在根目录中生成主 AGENTS.md 文件,以及包含特定于模式的 AGENTS.md
文件的 .bob/ 文件夹。在继续之前,验证 AGENTS.md 和 .bob/ 文件夹出现在项目根目录中。
查看生成的文件以了解 Bob 推断出的项目结构、技术栈和关键模式。此上下文直接提高了后续提示中
分析的质量。
生成代码质量摘要
代码质量摘要为工程师和审查员提供了整个代码库问题的结构化视图:反模式、缺少的保护措施、测试 覆盖率差距以及在项目生命周期中积累的不一致性。与 linter 报告不同,Bob 生成的质量摘要使用 人类可读的解释和严重性上下文综合跨语言和层的发现。
Galaxium Travels 代码库跨越三个不同的技术栈:Python(后端)、TypeScript(前端)和 Java (hold 服务)。构建你的提示以独立分析每个服务,然后生成统一的发现表。使用 context mentions 为 Bob 提供精确的文件范围,而不是让 Bob 猜测哪些文件相关。
开始新任务
点击 + 按钮开始新任务。重新开始可使此提示的上下文限制在你在此处提到的文件,而不是
携带 Bob 在 /init 期间读取的所有内容。
生成代码质量摘要
在 Agent 模式下,在聊天输入字段中输入以下提示:
Analyze the code quality of the Galaxium Travels application across all three
services.
For the Python backend, examine @booking_system_backend/server.py,
@booking_system_backend/models.py, @booking_system_backend/services, and
@booking_system_backend/tests.
For the TypeScript frontend, examine @booking_system_frontend/src.
For the Java hold service, examine
@booking_system_inventory_hold_service/src/main/java/com/galaxium/holdservice.
Produce a structured Markdown file named `docs/audit/code-quality-summary.md`.
The content should include the following sections:
1. An overview table listing each component, language, files analyzed, and
issue count by severity (Critical, High, Medium, Low).
2. Per-component findings, each with: severity label, issue title, file and
approximate line reference, description, and impact.
Focus on: missing input validation, inconsistent error handling, authentication
and credential storage patterns, test coverage gaps, type safety, and logging
practices. Do not suggest fixes — only report findings with evidence from the
source files.Bob 分析三个服务,如果尚不存在则创建 docs/audit/ 目录,创建 Markdown 文件,并在聊天界面
中输出摘要。报告包含你指定的部分和结构,其中的发现引用特定文件和代码行作为证据。
验证报告
在继续之前,在 Bob 文件资源管理器中打开 docs/audit/code-quality-summary.md 以确认文件已
创建,包含概览表和每个组件的发现。
运行依赖项审计
依赖项审计确定项目依赖的库是否固定到已知良好的版本,固定策略在多语言技术栈中是否一致,以及 任何依赖项配置实践是否引入不受控制的升级风险。这与 CVE 扫描不同:你正在评估版本管理纪律, 而不仅仅是已知漏洞。
Galaxium Travels 项目有三个依赖项清单:booking_system_backend/requirements.txt(Python)、
booking_system_frontend/package.json(Node.js)和
booking_system_inventory_hold_service/pom.xml(Java/Maven)。在你的 context mentions 中
包含所有三个。
开始新任务
点击 + 按钮开始新任务。
生成依赖项审计
在 Agent 模式下,在聊天输入字段中输入以下提示:
Audit the dependency manifests for all three services in the Galaxium Travels
repository.
Analyze @booking_system_backend/requirements.txt,
@booking_system_frontend/package.json, and
@booking_system_inventory_hold_service/pom.xml.
Produce a structured Markdown file named `docs/audit/dependency-audit.md`.
The content should include these sections:
1. Per-manifest findings table: package name, declared version or range,
pinning status (exact, caret/tilde range, or unpinned), and a brief
finding note.
2. Cross-cutting findings: consistency issues, missing tooling (lock files,
audit CI steps, vulnerability scanners), and version drift risks.
3. Findings that require immediate attention before a production deployment,
listed with rationale.
Report findings only. Do not generate upgrade commands or patch suggestions.Bob 分析清单并写入报告。它包括固定状态表和跨领域发现部分。
验证报告
打开 docs/audit/dependency-audit.md 以确认每个清单的表和跨领域发现部分在继续之前存在。
评估技术债务
技术债务评估评估随时间累积成本的结构、架构和运营决策。构建你的提示以将债务分为架构、安全、 运营准备和代码质量,并对每个项目的严重性和补救工作进行评级,以便领导层可以确定优先级。
以下提示在 context mentions 中包含 AGENTS.md,以便为 Bob 提供有关推断的架构和运营模式的
见解,这可以为架构和运营债务的评估提供信息。你在初始化项目上下文部分
运行的 /init 命令创建了 AGENTS.md 文件。
开始新任务
点击 + 按钮开始新任务。
生成技术债务评估
在 Agent 模式下,在聊天输入字段中输入以下提示:
Conduct a technical debt assessment of the Galaxium Travels application.
Analyze the full codebase across all three services:
@booking_system_backend, @booking_system_frontend, and
@booking_system_inventory_hold_service.
Also review @docker-compose.yml and @AGENTS.md for infrastructure and
operational context.
Produce a structured Markdown file named `docs/audit/technical-debt-assessment.md`.
The content should include these sections: Architecture Debt, Security Debt, Operational Readiness Debt, and Code Quality Debt.
For each debt item include:
- A severity label: [CRITICAL], [HIGH], [MEDIUM], or [LOW]
- An effort-to-resolve label: [DAYS], [WEEKS], or [MONTHS]
- A title
- The affected files or components
- A description of the debt and why it matters
- The consequence of leaving it unaddressed
Conclude with a summary table: category, count by severity, and total items.
Report findings only. Do not generate implementation plans or code.Bob 分析代码库并写入报告,为每个债务项目标记严重性和工作量估计。
验证报告
打开 docs/audit/technical-debt-assessment.md 以确认四个债务类别和摘要表在继续之前存在。
生成合规文档
合规文档将代码库的当前状态映射到监管机构、审计员和企业安全团队期望在生产系统中找到的控制措施。 对于非工程师利益相关者,此文档回答了这个问题:"此系统如何处理敏感数据,如何控制访问,差距在哪里?"
构建你的提示以涵盖数据分类、身份验证和访问控制、数据保护、审计跟踪覆盖范围和许可证合规性。
开始新任务
点击 + 按钮开始新任务。
生成合规文档
在 Agent 模式下,在聊天输入字段中输入以下提示:
Generate compliance documentation for the Galaxium Travels application,
suitable for sharing with security reviewers and compliance stakeholders.
Analyze the following files and directories:
@booking_system_backend/models.py,
@booking_system_backend/server.py,
@booking_system_backend/services,
@booking_system_backend/requirements.txt,
@booking_system_inventory_hold_service/src/main/java/com/galaxium/holdservice/domain,
@booking_system_inventory_hold_service/pom.xml,
@booking_system_frontend/src,
@booking_system_frontend/package.json,
@LICENSE.
Produce a structured Markdown file named `docs/audit/compliance-documentation.md`. The content should include these sections:
1. Data Classification — table of data elements, classification tier, storage
location, and retention policy.
2. Authentication and Access Control — table of controls, implementation status
(Implemented / Partial / Not Implemented), and a source reference or gap note.
3. Data Protection — table of controls, implementation status, and notes.
4. Audit Trail Coverage — what is logged, what is not, and where audit records
are stored.
5. License Compliance — table of key dependencies (Python, Node, and Java) with
their license and a compliance note.
6. Regulatory Applicability — brief assessment of GDPR, SOC 2, and PCI DSS
applicability given the data the system handles.
Use neutral, factual language. Do not recommend remediations.Bob 分析源文件并写入报告,将每个控制映射到带有代码引用的实施状态。
验证报告
打开 docs/audit/compliance-documentation.md 以确认所有六个部分在继续之前存在。
编译利益相关者审计报告
完成四个单独的分析后,要求 Bob 将它们组装成一个面向高管的审计报告。利益相关者报告与按主题 分析不同:它以发现摘要开头,优先考虑最可操作的项目,并提供非技术读者可以采取行动的推荐补救 顺序。
提示使用 context mentions 加载 Bob 在前面部分写入磁盘的四个报告。Bob 读取这些文件并将它们 合成为单个文档,而不是重新分析源代码,因此输出反映了你已经审查过的发现。
开始新任务
点击 + 按钮开始新任务。
生成利益相关者审计报告
在 Agent 模式下,在聊天输入字段中输入以下提示:
Using @docs/audit/code-quality-summary.md, @docs/audit/dependency-audit.md,
@docs/audit/technical-debt-assessment.md,
and @docs/audit/compliance-documentation.md, compile a consolidated
stakeholder audit report for the Galaxium Travels application.
The audience is engineering leadership and security reviewers who need to
assess the system's production readiness and compliance posture without
reading four separate documents.
Structure the report as follows:
1. Executive Summary: 2-3 paragraphs covering overall state, most critical
risks, and the highest-priority remediation categories.
2. Production Readiness Scorecard: a table scoring the system against six
dimensions (Authentication, Data Protection, Observability, Dependency
Health, Test Coverage, Operational Readiness) with a RAG status
(Red / Amber / Green) and a one-line rationale for each.
3. Critical and High Findings: a consolidated table of all Critical and High
severity findings from all four analyses, with category, finding title,
affected component, and effort to resolve.
4. Recommended Remediation Sequence: an ordered list of the top 5 items to
address first, with a brief rationale for the ordering.
5. Positive Findings: a brief section acknowledging controls and practices
that are already well-implemented.
Do not repeat all findings in full. Reference the detailed documents for
complete findings. Save the report as `docs/audit/stakeholder-audit-report.md`.Bob 读取四个保存的报告,综合其发现并创建 docs/audit/stakeholder-audit-report.md。因为 Bob
从你已经审查过的报告中工作,而不是重新分析源代码,所以合并报告与详细发现保持一致。
验证报告
打开 docs/audit/stakeholder-audit-report.md 以确认执行摘要、记分卡和五个部分存在。你现在
在 docs/audit/ 中拥有一套完整的审计文档,可以与利益相关者共享并用作补救计划的基准。
故障排除
Bob 的分析遗漏了服务或文件
如果 Bob 的输出缺少你期望看到的组件的发现,最可能的原因是提示未在 context mention 中包含 文件或目录,或者上下文窗口太满,Bob 无法在一次传递中读取所有引用的内容。
检查你的 context mentions
验证提示中的 @ 提及是否解析为正确的路径。在 Bob 聊天界面中,Bob 可能会指示是否解析了
context mention。如果 Bob 无法识别提及,则路径可能拼写错误或目录可能不存在于你的本地克隆中。
对于包含许多文件的目录,Bob 可能只读取一个子集。将范围缩小到最相关的子目录或枚举特定文件, 而不是引用整个文件夹。
将分析拆分为重点提示
不要使用涵盖所有三个服务的单个提示,而是运行三个单独的提示,每个服务一个,然后要求 Bob 合并发现。例如,在完成 Python 和 TypeScript 传递后,这是第三个重点提示:
The code quality analysis we ran earlier covered the Python backend and
TypeScript frontend. Run the same analysis for the Java hold service only,
using @booking_system_inventory_hold_service/src. Use the same output format
and severity labels as the earlier reports.每个重点分析完成后,要求 Bob 合并它们:
Combine the three per-service code quality analyses into a single unified
report using the same format we used for the initial report.报告在提示之间包含冲突的发现
运行多提示会话时,后续提示可能会产生似乎与早期提示相矛盾的发现。如果 Bob 从不同的文件读取 中得出不同的推论,或者如果早期发现不精确,则可能会发生这种情况。
识别冲突的声明
在新提示中引用两个发现,并要求 Bob 使用特定的文件引用解决差异。例如:
In the code quality summary you stated that error handling in server.py is
inconsistent. In the technical debt assessment you described the same issue
as absent error handling. Review @booking_system_backend/server.py and clarify
which description is more accurate, with a specific line reference.更新受影响的报告
在 Bob 产生权威发现后,要求 Bob 更新保存的报告文件中的特定部分。例如,如果技术债务评估更 准确,请要求 Bob 更新代码质量摘要:
Update the error handling finding in docs/audit/code-quality-summary.md to
use the corrected description. Do not change any other section.Bob 向分析添加未经请求的建议
当提示要求 Bob 在没有明确约束的情况下"分析"或"评估"时,Bob 通常会在发现旁边包含补救建议。 对于合规或审计报告,未经请求的建议可能会有问题:它们可能不正确,可能反映对目标环境的假设, 并且可能会使期望仅包含发现的文档的利益相关者感到困惑。
将指令 "Report findings only. Do not generate implementation plans, code, or remediation suggestions." 添加到任何重要的分析提示中。如果 Bob 已经生成了包含混合内容的 报告,请要求 Bob 删除建议。例如,如果代码质量摘要包含建议,请输入以下提示:
Remove all remediation suggestions, implementation guidance, and code examples
from docs/audit/code-quality-summary.md. Keep all finding descriptions,
severity labels, file references, and impact statements exactly as written.清理
要删除本教程中创建的工件:
- 删除包含五个生成报告的
docs/audit/目录。 - 如果你不想保留 Bob 生成的项目上下文,请删除
/init命令创建的AGENTS.md文件和.bob/文件夹。 - 删除你在设置你的工作区中克隆的
galaxium-travels目录。
后续步骤
在本教程中,你使用 IBM Bob 来:
- 使用
/init初始化项目上下文,以便 Bob 的分析反映项目的结构和技术栈 - 生成四个重点审计工件:代码质量摘要、依赖项审计、技术债务评估和合规文档。每个都由源文件 中的证据支持
- 将四个分析编译成一个利益相关者审计报告,其中包含生产准备记分卡和推荐的补救顺序
- 使用 Agent 模式和 context mentions 将每个报告持久化到磁盘,保持分析自包含且令牌高效
继续使用以下资源:
- 遵循 Audit code and generate reports 以生成开发工具 和 AI 代理可以操作的机器可读 SARIF 和 OSCAL 工件。
- 使用发现作为基准,然后遵循 Generate secure code with an actor-critic workflow 进行补救,而不重新引入此审计发现的问题。
- 阅读 Bob best practices 以获取更有效的 提示策略。