# Kylin Sentinel Agent

[![Tests](https://github.com/ArtForests/kylin-sentinel-agent/actions/workflows/tests.yml/badge.svg)](https://github.com/ArtForests/kylin-sentinel-agent/actions/workflows/tests.yml)

面向麒麟操作系统的安全智能运维 Agent：将自然语言运维请求转换为可审查、可授权、可执行、可追溯的工作流。

| 项目 | 信息 |
| --- | --- |
| 开发者 | 王泽睿 |
| 指导老师 | 董乐红 |
| 赛题 | 2026 中国软件杯 A2 · 面向麒麟操作系统的安全智能运维 Agent 设计与实现 |
| 默认模式 | 只读运行；写操作需要显式开启并通过策略与确认 |

![Kylin Sentinel Agent Web UI](figures/web-ui.png)

## 为什么做这个项目

让大模型直接执行系统命令会带来四类问题：规划结果不等于执行授权、工具权限边界过宽、高风险操作缺少人工确认、执行过程难以追溯。

Kylin Sentinel Agent 将“模型规划”与“系统授权”分离：LLM 只负责生成结构化计划，确定性的 Guardrail、Policy Kernel 和 Agent Firewall 决定计划能否执行；Executor 仅接受通过校验并绑定参数的授权结果。

| 遇到的问题 | 对应机制 |
| --- | --- |
| LLM 可能产生越权或提示注入计划 | Guardrail 检测危险意图、注入与敏感信息 |
| 规划结果不能直接作为执行依据 | Policy Kernel 按路径、命令、SQL、能力和影响范围做确定性授权 |
| 确认后参数可能被替换 | Agent Firewall 使用签名 receipt 绑定归一化参数 |
| 高风险任务需要中断后继续 | Workflow Runtime 支持暂停、确认、恢复与失败归因 |
| 运维操作难以复盘 | Trace、Audit、Session 和 Memory 记录完整链路 |

## 系统架构

![Kylin Sentinel Agent Architecture](figures/kylin-sentinel-agent-architecture.png)

核心执行链路：

```text
Web UI / HTTP API / MCP Client
              |
              v
      LLMPlanner / Rule Planner
              |
              v
 Guardrail -> Policy Kernel -> Agent Firewall
              |
              v
      MCP Dispatcher / Executor
              |
              v
 Sensors / Safe Actions / Audit / Memory
```

## 主要能力

- Web UI、HTTP API、流式对话接口和内置 MCP JSON-RPC 网关。
- 系统、磁盘、进程、网络、服务、文件和配置等运维巡检工具。
- 受控 Shell、服务操作、日志轮转、临时文件清理和 MariaDB 只读查询。
- `allow / require_confirm / deny` 三级策略决策与参数绑定回执。
- 工作流暂停、恢复、回滚信息、失败归因和全链路审计。
- 本地知识库、会话记忆、记忆投毒隔离和敏感内容脱敏。
- OpenTelemetry 可选观测，以及 OpenAI-compatible LLM 可选接入。

## 安全边界

- 默认设置 `KYLIN_WRITE_ENABLED=0`，只读能力优先。
- LLM 不直接获得工具执行权，模型评分不能替代确定性策略。
- 私钥、凭据、敏感路径和危险命令默认拒绝或进入人工确认。
- 写操作必须同时通过写开关、工具策略、参数校验与确认机制。
- MariaDB 工具限制为单一配置数据库的只读查询。
- Prompt、LLM 输入输出和审计数据进入运行时前执行敏感信息脱敏。

## 快速开始

环境要求：Linux / Kylin Advanced Server V11，Python 3.10 及以上。

```bash
python3 -m venv .venv_mcp
. .venv_mcp/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

KYLIN_WRITE_ENABLED=0 python app.py
```

默认监听：

```text
http://127.0.0.1:8000
```

健康检查：

```bash
curl http://127.0.0.1:8000/api/health
```

默认使用本地规则与 mock provider，不需要外部 API Key。启用外部 LLM 时，请通过环境变量传入 `KYLIN_LLM_API_KEY`，不要写入源码、文档或提交历史。

## API 与 MCP

普通对话：

```bash
curl -s http://127.0.0.1:8000/api/chat \
  -H 'Content-Type: application/json' \
  -d '{"message":"帮我查看系统状态"}'
```

列出内置 MCP 工具：

```bash
curl -s http://127.0.0.1:8000/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```

独立 FastMCP 服务可按能力拆分启动：

```bash
python sdk_server_app.py --server ops-sensor-server
python sdk_server_app.py --server ops-action-server
python sdk_server_app.py --server audit-server
```

## 测试与验收

运行单元测试：

```bash
python -m unittest discover -s tests -v
```

运行完整 readiness audit：

```bash
python scripts/readiness_audit.py --full \
  --venv-python .venv_mcp/bin/python
```

当前公开版本包含 **159 项 unittest**，覆盖策略、Guardrail、Firewall、Executor、MCP、工作流、会话、记忆、观测与运行时脱敏。

## 项目结构

```text
kylin_sentinel/   核心 Agent、策略、工具、执行器与 Web/API
tests/            单元测试
scripts/          readiness、评测、性能和验收脚本
deploy/           systemd、sudoers 与策略示例
evals/            Prompt Injection 与 MCP 滥用测试集
knowledge_base/   本地运维知识库
docs/             需求、设计、说明、测试、性能和部署文档
figures/          Web UI 与系统架构图
```

## 技术文档

- [软件功能需求分析](docs/requirements.md)
- [软件功能设计](docs/design.md)
- [软件项目说明书](docs/project-overview.md)
- [软件功能测试报告](docs/functional-testing.md)
- [软件性能测试报告](docs/performance-testing.md)
- [软件安装与部署](docs/deployment.md)

## 使用提示

本项目包含系统巡检与受控运维能力。请仅在本人拥有管理权限的测试环境中运行；首次使用保持只读模式，并在启用写操作前检查策略文件、工具白名单和确认流程。