# 02 — 网络安全

> GB/T 22239-2019 第三级「网络和通信安全」控制点映射。

## 1. 维度说明

AgentKit 部署在客户内网 K8s 集群，网络安全的边界由 Ingress 控制，
内部东西向流量由 K8s 网络模型与（待补齐的）NetworkPolicy 控制。
AgentKit 自身实现：

- **已实现**：Ingress TLS 终止、OTel 安全审计（日志/trace）、
  Redis/PG 密码鉴权（基础设施层）、API 限流。
- **P0 补齐项**：NetworkPolicy 模板（东西向流量隔离）、
  审计日志保留策略（180 天，KTD-9）。
- **P1 参考**：OTel exporter mTLS、网络入侵检测接入。

## 2. GB/T 22239-2019 三级要求（简要）

| 控制点 ID | 要求摘要 |
|-----------|----------|
| NET-01 | 网络架构：划分网络区域，避免单点故障 |
| NET-02 | 边界防护：边界实施访问控制和安全过滤 |
| NET-03 | 访问控制：网络层访问控制策略，最小权限 |
| NET-04 | 入侵防范：网络入侵检测，恶意流量检测 |
| NET-05 | 安全审计：网络审计日志，覆盖关键网络活动 |
| NET-06 | 恶意代码防范：网络边界恶意代码检测 |
| NET-07 | 安全审计日志保留：日志保留期满足合规要求 |
| NET-08 | 资源控制：会话与带宽限制，防止资源耗尽 |

## 3. AgentKit 实现映射

### 3.1 网络架构（NET-01）— 已实现

AgentKit K8s 部署采用单 Ingress 入口 + 内部 Service 架构：

```
外网/办公网 ── HTTPS ──> Ingress (nginx, TLS 终止)
                              │
                              ▼
                    AgentKit Service (ClusterIP)
                              │
                              ▼
                    AgentKit Pod (:8001 API, :8002 GUI)
                              │
                ┌─────────────┼─────────────┐
                ▼             ▼             ▼
             Redis         PostgreSQL    OTel Collector
          (ClusterIP)    (ClusterIP)   (ClusterIP)
```

- **Ingress 是唯一对外入口**：[deploy/helm/agentkit/templates/ingress.yaml](file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/templates/ingress.yaml)
- **Service 类型为 ClusterIP**（不直接对外暴露）：
  [deploy/helm/agentkit/values.yaml](file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/values.yaml)
  （`service.type: ClusterIP`）
- **API 与 GUI 走分离路径**：`/api` → API Service，`/` → GUI Service

### 3.2 边界防护（NET-02）— 已实现

Ingress 启用 TLS 终止，所有外网流量强制 HTTPS：

```yaml
ingress:
  enabled: true
  className: nginx
  tls:
    enabled: true
    secretName: agentkit-tls   # 引用 secrets.tlsServerCert
```

- TLS 证书通过 cert-manager 自动续期或手动签发（365 天轮换）。
- HTTP→HTTPS 跳转由 nginx ingress controller 默认配置提供
  （客户侧 ingress controller 责任）。
- 证书私钥通过 Sealed Secret / External Secret 注入（KTD-4 / R2a）。

**参考文件**：
[deploy/helm/agentkit/templates/ingress.yaml](file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/templates/ingress.yaml)
[deploy/helm/agentkit/values.yaml](file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/values.yaml)（`ingress` 段、`secrets.tlsServerCert` slot）

### 3.3 访问控制 / NetworkPolicy（NET-03）— P0 补齐项

**当前状态：P0**。Helm Chart 暂无 NetworkPolicy 模板，
Pod 间东西向流量默认全通（K8s 默认网络模型）。

**P0 补齐计划**：

1. 新增 `deploy/helm/agentkit/templates/networkpolicy.yaml`。
2. 默认 deny-all，按白名单放行：
   - Ingress → AgentKit Pod（8001/8002）
   - AgentKit Pod → Redis（6379）
   - AgentKit Pod → PostgreSQL（5432）
   - AgentKit Pod → OTel Collector（4317）
3. 命名空间隔离：AgentKit 独立 namespace，跨 namespace 流量显式声明。

**当前缓解**：Service 全部 ClusterIP（不对外），Redis/PG 由客户 K8s 集群
内部网络策略保护（客户侧责任）。

### 3.4 入侵防范（NET-04）— P1 参考

**当前状态：P1**。AgentKit 自身不部署网络 IDS，
依赖客户侧网络骨干的 IDS / IPS。

- API 层面：[RateLimitMiddleware](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/middleware.py)
  实现单进程滑动窗口限流，Webhook 入站端点单独限流
  （[src/agentkit/server/routes/channels.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/routes/channels.py)）。
- 异常登录：JWT 验证失败、SCIM token 校验失败返回 401
  （[scim/router.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/scim/router.py)
  使用 `hmac.compare_digest` 恒定时间比较）。

**P1 补齐计划**：接入客户 SIEM，将 AgentKit OTel 日志投递到客户
入侵检测平台，由 SIEM 做 abnormal pattern 检测。

### 3.5 安全审计（NET-05）— 已实现

AgentKit 通过 OpenTelemetry（U1，强制依赖）实现网络活动审计：

- **HTTP 请求 trace**：FastAPI Instrumentor 自动埋点，每个请求生成 span，
  含 HTTP method/path/status/duration。
  [src/agentkit/telemetry/setup.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/telemetry/setup.py)
  （`FastAPIInstrumentor`）
- **审计事件 span**：RBAC 角色变更、deprovisioning 写入 OTel span event
  （[src/agentkit/server/auth/audit.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/audit.py)）。
- **SCIM 推送失败告警**：span event `scim.push.failure`
  （[scim/router.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/scim/router.py)）。
- **终端命令审计**：每条终端命令写入 `terminal_audit_logs` 表
  （[terminal_security.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/terminal_security.py)）。

OTLP gRPC 导出到内部 collector
（[values.yaml](file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/values.yaml)
`otel.endpoint: http://otel-collector:4317`）。

### 3.6 恶意代码防范（NET-06）— 待评估

**当前状态：待评估**。网络边界恶意代码检测由客户网络骨干的
防病毒网关 / 沙箱负责。AgentKit 不在网络边界位置。

AgentKit 侧的缓解：

- 容器镜像来自可信构建（CI/CD），不在运行时下载可执行文件。
- 终端命令执行受 6 层白名单 + 危险检测约束（R7a），
  限制任意命令执行能力（详见 `04-application.md` §2）。

### 3.7 安全审计日志保留（NET-07）— P0 补齐项

**当前状态：P0**。审计日志保留策略未在代码中强制实施：

- `auth_audit_log` 表（SQLite）和 `terminal_audit_logs` 表无自动清理 /
  归档策略，依赖运维手动管理。
- OTel collector 侧的日志保留由客户可观测性平台配置，AgentKit 不控制。

**P0 补齐计划**：

1. 在 Helm values 增加 `audit.retentionDays: 180` 配置（KTD-9）。
2. 实现审计日志归档 CronJob：超过 180 天的记录导出到对象存储（客户侧）
   并从主表清理。
3. OTel collector 配置 180 天保留策略（与客户可观测性团队协同）。

### 3.8 资源控制（NET-08）— 已实现

AgentKit 在应用层与容器层均实现资源控制：

- **容器层**：Pod resources requests/limits
  （[values.yaml](file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/values.yaml)
  `resources` 段，CPU 250m~1000m / Memory 512Mi~2Gi）。
- **应用层**：[RateLimiter](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/middleware.py)
  实现 IP 维度滑动窗口限流，Webhook 入站端点独立限流
  （[channels.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/routes/channels.py)）。
- **会话超时**：终端 session 闲置 1800s 自动断开
  （[terminal_server.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/routes/terminal_server.py)
  `SESSION_IDLE_TIMEOUT = 1800`）。
- **JWT 短时效**：access token 15min
  （[jwt_utils.py](file:///Users/chiguyong/Code/Fischer-agentkit/src/agentkit/server/auth/jwt_utils.py)
  `ACCESS_TOKEN_TTL`）。

## 4. OTel exporter mTLS（P1 参考）

**当前状态：P1**。OTel exporter 通过 bearer token 鉴权
（[values.yaml](file:///Users/chiguyong/Code/Fischer-agentkit/deploy/helm/agentkit/values.yaml)
`secrets.otelExporterToken` slot），未启用 mTLS。

Helm Chart 已预留 `secrets.mtlsClientCert` slot（用于下游服务 mTLS），
但 OTel exporter 侧的 mTLS 配置待补齐。

**P1 补齐计划**：

1. 在 OTel SDK 初始化时配置 `OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE` /
   `OTEL_EXPORTER_OTLP_CLIENT_KEY` / `OTEL_EXPORTER_OTLP_CA_CERT` 环境变量。
2. OTel collector 侧启用 mTLS 服务端证书验证。
3. 复用 `secrets.mtlsClientCert` slot 注入客户端证书。

## 5. 测评建议

1. **NET-01 / NET-02 / NET-05 / NET-08**：直接展示 Helm Ingress + OTel +
   限流配置即可。
2. **NET-03 / NET-07**：P0 补齐项，需在测评前完成 NetworkPolicy 模板和
   审计日志保留 CronJob。
3. **NET-04 / NET-06**：依赖客户侧网络骨干，由客户网络团队提供 IDS /
   恶意代码检测证据。