TSAssistant：基于智能体框架与人在回路的自动化安全评估系统设计与实践

1. 项目概述：当自动化评估遇上“人”的智慧

在软件开发生命周期中，安全评估是一个既关键又繁重的环节。无论是新功能上线前的代码审计，还是对现有系统进行漏洞扫描，传统方式往往依赖安全专家手动执行或运行自动化工具后人工解读海量报告。这个过程耗时耗力，且高度依赖专家的个人经验和状态，容易产生疏漏。TSAssistant 这个项目标题，精准地指向了当前安全工程领域的一个核心痛点：如何将自动化工具的效率和人类专家的深度判断力有效结合，构建一个既能“跑得快”又能“看得准”的智能评估框架。

“Human-in-the-Loop”和“Agentic Framework”是这里的两个关键词，它们共同定义了TSAssistant的灵魂。它不是要取代安全专家，而是将专家从重复、机械的告警筛选和初步分析中解放出来，让他们专注于更高层次的策略制定、复杂漏洞的确认和风险评估。你可以把它想象成一个不知疲倦的初级安全分析师，它能够7x24小时地运行各种扫描工具，按照预设的规则对结果进行初步分类、去重和优先级排序，然后将那些真正需要人类智慧介入的、模糊的或高风险的案例，以结构化的方式呈现在专家面前，等待决策。这个“决策”又会反馈给系统，成为其优化下一次自动化判断的“养料”。

因此，TSAssistant的核心价值在于构建一个“评估-决策-学习”的闭环。自动化部分负责大规模、标准化的“评估”，人类专家负责关键节点的“决策”，而整个框架（Agentic Framework）则负责根据决策结果进行“学习”和流程调度，使得整个安全评估流程越来越智能、越来越精准。它瞄准的应用场景非常广泛，从持续集成/持续部署（CI/CD）流水线中的自动安全门禁，到对大型代码仓库的周期性深度安全体检，再到针对特定攻击面的专项靶场测试，都能通过这个框架提升效率和覆盖率。

2. 框架核心设计：拆解“智能体”与“人在回路”的协同机制

要理解TSAssistant，我们必须深入其两个核心设计理念：智能体框架和人在回路。这并非简单的工具链拼接，而是一套深思熟虑的、旨在最大化人机协同效能的系统架构。

2.1 Agentic Framework：不止于脚本，而是有“意图”的智能体

传统的自动化安全评估，通常是一系列脚本的线性执行：先调用SAST工具扫描，再调用DAST工具测试，最后生成报告。这种模式僵硬、缺乏上下文感知和自适应能力。TSAssistant所采用的“智能体框架”则截然不同。在这里，“智能体”可以被理解为具有特定目标、能感知环境、能自主采取行动以实现目标的软件实体。

在TSAssistant中，可能会设计多种职能的智能体：

• 采集智能体：它的“意图”是获取目标系统的完整状态信息。它不会傻傻地只运行一种扫描器，而是根据目标类型（Web应用、移动应用、API服务）和项目阶段（开发、测试、生产），动态组合调用不同的信息收集工具，如代码仓库分析、依赖成分分析、网络空间测绘等。
• 分析智能体：它的核心“意图”是理解风险。它接收采集智能体传来的原始数据（包括漏洞扫描报告、依赖关系、配置信息等），并应用一系列规则引擎、机器学习模型或知识图谱，进行关联分析和初步风险评估。例如，它将一个SQL注入漏洞的上下文（是否在认证后、输入是否可控、数据库类型）与当前系统的安全控制措施进行关联，从而计算出一个更动态的初始风险分数，而不是单纯依赖工具的“高、中、低”等级。
• 协调智能体：这是框架的“大脑”，其“意图”是确保整个评估流程高效、有序地朝向最终目标（完成安全评估）推进。它负责任务调度、智能体间的通信、状态管理以及最重要的——决定何时需要将问题“上报”给人类专家。它维护着整个评估的上下文，确保分析智能体不会在无关紧要的低风险问题上反复请求人工介入。

这种基于智能体的设计，使得框架具备了模块化、可扩展和自适应的特性。新的扫描工具或分析模型可以很容易地封装成新的智能体加入系统；智能体之间可以通过标准的消息格式进行协作，从而处理更复杂的评估场景。

2.2 Human-in-the-Loop：精准定义人机交互的“握手点”

“人在回路”是TSAssistant区别于全自动黑盒系统的关键。但“回路”设计得好坏，直接决定了框架的实用价值。糟糕的设计会让专家被海量的、无意义的提示所淹没，变成“人在干扰环”；优秀的设计则能让专家在关键时刻发挥决定性作用。TSAssistant需要精心设计几个核心的“握手点”：

1. 模糊性裁决点：当分析智能体对某个潜在漏洞的判断置信度低于某个阈值时（例如，静态分析发现一个可疑的数据流，但无法确定该数据流是否最终由用户可控），它将创建一个裁决任务，附上所有相关代码片段、数据流图和工具原始输出，提交给人类专家。专家只需回答“是漏洞”、“不是漏洞”或“需要更多信息”，这个决策会被记录并用于训练分析智能体的判断模型。
2. 业务逻辑风险确认点：自动化工具很难理解业务逻辑。例如，一个“绕过验证查看他人订单”的漏洞。扫描器可能发现了一个权限检查不严格的API，但无法确认这是否符合业务设计。此时，协调智能体会将该API的端点、参数以及可能的越权访问路径，连同业务功能描述，一并提交给熟悉业务的安全专家或产品经理进行确认。
3. 风险接受与例外审批点：对于已确认但暂时无法修复或风险可接受的漏洞（例如，一个低危漏洞修复成本极高），框架可以生成一个风险接受审批单，流转至技术负责人或安全官处，完成线上审批流程。这个审批结果会作为知识录入系统，避免下次评估时重复标记同类已接受风险。
4. 策略调优与反馈点：专家在交互过程中，可以对智能体的行为提供直接反馈。例如，标记某个规则为“过于敏感”或“缺失”，这些反馈会直接影响分析智能体的规则权重或触发协调智能体启动规则库更新流程。

注意：设计“握手点”时，必须提供充足、结构化的上下文信息给人类专家，避免让专家再去翻查原始报告或代码。同时，交互界面应尽可能简洁，提供“一键式”的常见决策选项，最大限度降低专家的认知负荷和操作成本。

3. 系统架构与核心组件实现解析

一个可行的TSAssistant架构可以分为四层：交互层、协调层、智能体层和数据层。每一层都有其明确的职责和实现要点。

3.1 协调层：以工作流引擎为核心的中枢

协调层是框架的指挥中心，通常由一个可编排的工作流引擎（如Apache Airflow, Prefect，或基于Camunda等BPMN引擎定制）来实现。它不关心具体的安全知识，只关心流程和任务。

• 流程定义：我们将一次完整的目标安全评估定义为一个工作流。这个工作流可能包含并行任务（同时进行SAST和SCA扫描）、串行任务（先完成信息收集，才能进行关联分析）和条件分支（如果发现高危漏洞，则立即暂停并告警）。
• 任务调度与状态管理：协调器负责实例化工作流，将每个步骤转化为具体的“任务”，分发给对应的智能体执行，并持久化跟踪每个任务的状态（等待中、执行中、成功、失败、需人工干预）。
• 上下文传递：它维护一个全局的“评估上下文”对象，随着工作流推进，不断丰富其内容。例如，采集智能体完成扫描后，会将报告存储到数据层，并将报告的唯一标识符和元数据（如目标名称、工具类型、时间戳）写入上下文。分析智能体则从上下文中获取这些标识符，再去拉取详细数据进行分析。
• 人工任务集成：这是关键。当某个智能体（通常是分析智能体）产生了一个需要人工介入的“裁决任务”时，它会通过协调层创建一个“用户任务”。协调层将此任务与具体的用户或用户组关联，并更新工作流状态为“等待中”。此时，工作流会在此节点暂停，直到通过交互层收到人类的响应后，才继续推进。

3.2 智能体层：标准化接口下的能力单元

智能体层是具体干活的单元。每个智能体都应遵循统一的接口规范，例如提供一个execute(context)方法，接收协调层传来的上下文，执行后返回结果。实现时需要注意：

• 无状态设计：智能体本身不应保存任务状态，所有状态由协调层管理。这便于水平扩展和容错。
• 工具封装：一个智能体可以封装一个单一工具（如BanditSASTAgent），也可以封装一个复杂的分析逻辑（如CorrelationAnalysisAgent）。对于调用外部命令行工具的场景，需要做好超时控制、输出解析和错误处理。
• 消息队列解耦：智能体与协调层之间可以通过消息队列（如RabbitMQ, Redis Streams, Apache Kafka）进行通信。协调层将任务发布到特定主题，对应的智能体作为消费者订阅并处理。这提高了系统的异步处理能力和可靠性。

3.3 交互层：为人类专家打造的高效控制台

交互层是“人在回路”的物理界面。它通常是一个Web应用，需要提供以下核心功能：

• 仪表盘：总览所有正在运行和已完成的评估任务，显示关键指标（如待处理裁决数、平均处理时间、漏洞趋势）。
• 任务队列：这是核心界面，以清晰列表展示所有待处理的“人工裁决任务”。每个任务条目应包含：目标名称、问题类型（如“模糊的XSS”、“业务逻辑权限确认”）、初始风险评级、提交时间、以及一个“处理”按钮。
• 任务详情与决策面板：点击处理按钮后，应在一个页面内展示决策所需的所有信息。这通常需要分为多栏：
  • 左栏：问题详细描述，由分析智能体生成的自然语言摘要。
  • 中栏：关键证据展示。例如，对于代码漏洞，应嵌入代码查看器，高亮显示相关代码行；对于配置问题，展示配置文件片段；对于业务逻辑问题，提供API调用序列图。
  • 右栏：决策面板。提供预设的按钮（如“确认漏洞-高危”、“误报”、“需更多信息-请补充XX数据”），以及一个文本输入框供专家填写备注。决策应尽可能一键完成。
• 知识库联动：在专家决策时，系统应能自动联想并展示历史上类似的案例及其处理结果，辅助专家判断。

3.4 数据层：支撑持续学习的知识基石

数据层不仅用于存储原始报告和任务日志，更重要的是构建一个可供智能体学习的知识库。

• 原始数据存储：使用对象存储（如AWS S3, MinIO）存放扫描工具生成的原始HTML/XML/JSON报告。
• 结构化漏洞库：将原始报告解析后，把漏洞信息结构化存储到关系型数据库（如PostgreSQL）中。表结构设计需包含目标信息、漏洞类型、位置、工具原始等级、上下文特征等字段。
• 决策日志库：专门记录每一次人工裁决的详细信息，包括问题特征、专家决策结果、决策理由、处理专家等。这是后续训练机器学习模型最宝贵的标签数据。
• 向量知识库：为了支持更智能的联想和问答，可以将历史案例的描述、代码片段、解决方案通过嵌入模型转换为向量，存入向量数据库（如Milvus, Pinecone）。当新问题出现时，分析智能体可以快速检索相似历史案例，参考其处理方式，甚至直接给出处理建议。

4. 关键技术与实操挑战

实现TSAssistant框架，会面临一系列技术挑战，需要做出合适的选择。

4.1 智能体间的通信与数据格式标准化

这是实现协同的基础。智能体之间需要交换数据，例如采集智能体将扫描结果传递给分析智能体。必须定义一个统一的、可扩展的中间数据格式。推荐采用JSON Schema来规范核心数据对象，例如定义一个SecurityFinding对象：

{ "id": "uuid", "target": "example.com/api/v1", "tool": "ZAP", "type": "SQL_INJECTION", "location": { "file": "src/controller/user.go", "line": 42, "endpoint": "POST /user/query" }, "raw_severity": "HIGH", "confidence": 0.75, "context": { "data_flow": ["request.param.id", "db.query"], "sink_function": "db.Exec" }, "evidence": "Raw output snippet from tool...", "timestamp": "2023-10-27T10:00:00Z" }

所有智能体都生产和消费符合该模式的数据，确保信息无损、准确地传递。协调层负责将这类对象放入上下文。

4.2 裁决置信度模型的设计

分析智能体何时应该将问题上交给人？这需要一个置信度模型。一个简单的初版模型可以是基于规则加权：置信度 = 工具置信度权重 * 规则匹配度 + 上下文完备性权重 * 上下文分数

• 工具置信度权重：不同工具对同类漏洞的检出准确率不同，需要根据历史数据赋予不同权重。
• 规则匹配度：当前漏洞特征与知识库中已确认漏洞模式的匹配程度。
• 上下文完备性权重与分数：是否能完整追踪数据流？是否明确识别了输入源和危险函数？越完备，分数越高。

当最终置信度低于预设阈值（如0.7）时，则判定为“模糊”，需要人工裁决。这个模型可以随着决策日志的积累，逐步用机器学习模型（如基于特征分类的模型）进行替换和优化。

4.3 与现有DevOps工具链的集成

TSAssistant必须能够无缝嵌入现有的CI/CD流水线。这意味着：

• 触发机制：除了手动触发，应支持Webhook，以便在代码推送、合并请求创建或发布构建完成时自动启动评估流程。
• 门禁反馈：评估结果需要能反馈回流水线。例如，在GitLab CI或GitHub Actions中，如果协调层最终判定存在未解决的高危漏洞，TSAssistant应能通过API调用使得流水线任务失败，并生成详细的评论到合并请求中，附上漏洞链接和裁决记录。
• 凭证管理：安全扫描通常需要访问凭证（如仓库访问令牌、测试环境账号）。框架需要与公司的密钥管理服务（如HashiCorp Vault, AWS Secrets Manager）集成，安全地获取和使用这些凭证，而不是硬编码在配置里。

4.4 性能、扩展性与可靠性考量

• 异步与并行：工作流引擎应支持任务并行执行。例如，对大型单体应用，可以将其按模块拆分，并行启动多个SAST扫描智能体实例进行分析，最后由一个智能体汇总结果。
• 智能体池化：对于耗时的智能体（如动态扫描），可以采用池化技术，预先启动多个实例待命，避免每次任务都经历冷启动开销。
• 状态持久化与容错：工作流引擎和任务队列的状态必须持久化。如果某个智能体处理任务时崩溃，协调层应能感知到（通过心跳或超时机制），并将任务重新分配给其他健康实例，确保评估流程不会意外中断。
• 结果缓存：对于短期内未变更的代码目标，其SAST扫描结果可以缓存。协调层在启动流程前可以先检查缓存有效性，避免重复计算。

5. 部署实践与运维要点

将TSAssistant从概念落地到生产环境，需要细致的部署和运维策略。

5.1 技术栈选型建议

以下是一个基于云原生理念的参考技术栈，它平衡了能力、复杂度和社区生态：

5.2 分阶段实施路线图

不建议一开始就追求大而全的系统。建议采用渐进式路线：

1. 阶段一：核心闭环验证（1-2个月）

   • 目标：验证“采集->分析->人工裁决->反馈”的最小闭环。
   • 实现：选择一个核心漏洞类型（如SQL注入），手动编写一个简单的采集智能体（调用一个SAST工具）和一个规则分析智能体（基于正则或简单规则）。使用轻量级工作流引擎（甚至可以用Celery+Flask模拟）和基础数据库。构建一个最简单的Web界面处理人工裁决。
   • 产出：证明流程可行，并开始积累最初的决策日志数据。

2. 阶段二：功能扩展与集成（3-6个月）

   • 目标：支持更多工具和漏洞类型，集成到CI/CD。
   • 实现：增加更多采集智能体（SCA、DAST等）。完善分析智能体的规则引擎。实现与GitLab/GitHub的Webhook集成，实现基本的流水线门禁。升级数据模型和交互界面。
   • 产出：可在实际项目中部分替代人工初级筛查，在CI环节自动拦截明确的高危漏洞。

3. 阶段三：智能化与优化（持续）

   • 目标：引入机器学习，优化置信度模型和自动裁决准确率。
   • 实现：基于阶段一、二积累的决策日志，训练分类模型，用于辅助裁决或自动处理高置信度问题。引入向量知识库，实现案例检索。优化系统性能和用户体验。
   • 产出：系统智能化程度显著提升，人工介入比例逐渐降低，形成真正的“增强智能”循环。

5.3 安全与权限管控

系统本身必须是安全的，因为它处理敏感的安全数据。

• 认证与授权：交互层需集成公司统一的SSO（如OAuth 2.0）。在系统内部实现基于角色的访问控制（RBAC），例如：“安全专家”角色可以处理所有裁决，“开发人员”角色只能查看和处理自己项目相关的低危问题裁决。
• 数据加密：所有静态数据（数据库、对象存储）应加密。智能体间通信的消息，如果涉及敏感信息，应考虑使用TLS或端到端加密。
• 审计日志：所有用户操作（登录、决策、配置修改）和系统关键事件（任务触发、智能体异常）都必须记录详细的审计日志，并接入公司的日志管理平台，满足合规性要求。
• 智能体沙箱：对于执行不确定代码的智能体（如动态分析插件），应考虑在沙箱环境（如gVisor, Firecracker微虚拟机）中运行，防止逃逸影响主机系统。

6. 常见问题与效能提升技巧

在实际构建和运行TSAssistant过程中，你会遇到一些典型问题。以下是一些实录的排查思路和提升效能的技巧。

6.1 智能体执行超时或失败

这是最常见的问题之一。一个采集智能体卡住，会导致整个工作流停滞。

• 排查：
  1. 检查协调层日志：确认任务是否成功下发到消息队列。
  2. 检查智能体日志：查看智能体容器的标准输出和错误日志。最常见的原因是工具本身卡死（如网络超时、目标无响应）或资源不足（内存溢出）。
  3. 检查依赖服务：智能体是否需要访问数据库、内部API或其他服务？确认这些服务的连通性和健康状况。
• 解决与预防：
  • 设置超时：在协调层给每个任务类型设置合理的超时时间（如SAST扫描30分钟，DAST扫描2小时）。超时后，协调层应标记任务失败，并可能触发重试或告警。
  • 资源限制：为智能体容器配置CPU和内存限制，防止单个任务耗尽主机资源。
  • 实现健康检查：智能体应提供健康检查端点（如/health），协调层定期检查，及时剔除不健康的实例。
  • 任务幂等性设计：确保智能体的任务执行是幂等的，即相同输入多次执行结果相同。这样失败重试才是安全的。

6.2 人工裁决任务积压，专家处理不过来

这违背了提升效率的初衷，通常是因为阈值设置不合理或问题呈现方式不佳。

• 排查：
  1. 分析任务类型分布：查看积压的任务中，大部分属于哪一类？是“模糊性裁决”过多，还是“业务逻辑确认”类任务处理太慢？
  2. 审查置信度阈值：当前分析智能体的置信度阈值（如0.7）是否过低？导致大量本可自动判断的低置信度问题涌向人工。
  3. 调研专家反馈：直接与专家沟通，处理每个任务平均需要多久？时间主要花在什么地方（查找代码、理解上下文）？
• 解决与优化：
  • 动态调整阈值：初期可以设置较低的阈值，多收集人工裁决数据。随着数据积累和模型优化，逐步提高阈值，让系统更“自信”地自动处理更多问题。
  • 优化任务界面：如果专家时间花在查找信息上，就在任务详情页直接嵌入代码仓库的链接并定位到行，提供更直观的数据流图，将关键证据前置。
  • 引入分级处理：并非所有裁决都需要资深专家。可以设置规则：低风险/常见类型的模糊问题，可以由初级安全员或甚至开发负责人处理。在系统中配置不同的路由规则。
  • 提供批量处理功能：对于明显是同一类误报或低危问题，允许专家勾选多个任务进行批量“标记为误报”或“接受风险”操作。

6.3 误报率居高不下，专家对系统失去信任

如果系统持续推送大量显而易见的误报，专家很快就会将其忽略，导致真正的问题也被遗漏。

• 根源分析：
  • 工具本身误报：某些SAST工具规则过于宽泛。
  • 上下文分析不足：分析智能体未能充分利用代码上下文进行过滤。例如，一个调用了危险函数eval()的代码，如果其输入是硬编码的字符串常量，这通常不是漏洞，但工具可能仍会报告。
  • 规则库陈旧：未及时更新规则以排除已知的框架误报模式。
• 优化策略：
  • 建立误报知识库：每次专家标记“误报”时，不仅记录结果，更关键的是提取导致误报的“模式特征”（如：调用函数=eval， 且输入源=常量字符串）。分析智能体在后续分析中，应优先查询误报知识库，匹配成功则直接过滤，不再上报。
  • 实施工具调优：针对选用的扫描工具，进行深入的规则调优。禁用已知高误报的规则，调整规则的严重性级别。这是一个持续的过程。
  • 增强上下文分析：投入资源提升分析智能体的代码分析能力，例如构建更精确的数据流图，识别净化函数（如htmlspecialchars），如果数据流经过了净化，则应降低漏洞置信度或直接排除。

6.4 系统性能瓶颈分析

随着评估目标和频率增加，系统可能变慢。

• 瓶颈定位：
  1. 监控指标：监控消息队列长度、数据库连接数、智能体任务等待时间、API响应时间。
  2. 性能剖析：对耗时最长的智能体进行性能剖析，看是工具本身慢，还是数据处理逻辑慢。
• 优化手段：
  • 水平扩展智能体：对于无状态且耗时的智能体（如动态扫描），可以通过增加Kubernetes Deployment的副本数来并行处理更多任务。
  • 结果缓存：如前所述，对未变更的代码目标实施扫描结果缓存。可以基于代码仓库的commit hash作为缓存键。
  • 数据库优化：对SecurityFinding等核心查询表建立合适的索引（如target_id,status,created_at）。定期归档或清理历史数据。
  • 异步化处理：交互层的所有耗时操作（如生成大型报告）都应设计为异步任务，避免阻塞用户请求。

我个人在设计和实施这类系统的体会是，最难的不是技术实现，而是流程和人的融合。初期一定要让安全专家深度参与设计，特别是交互界面和裁决逻辑的设计，确保系统是“辅助”他们，而不是“指挥”他们。从一个非常小的、具体的场景开始，快速做出一个能用的原型，哪怕只有一两个智能体，然后让专家试用、吐槽、改进。这个快速反馈循环，比一开始就规划一个庞大完美的架构要重要得多。系统在运行中积累的数据（尤其是决策日志）是其最宝贵的资产，是它从“自动化”走向“智能化”的燃料，因此从一开始就要设计好数据模型，确保这些高质量的数据能被有效地收集和利用。