# 🚨 告警查看指南

Runtime Security Guard 提供多种方式查看安全告警。

---

## 📋 目录

1. [命令行查看](#命令行查看)
2. [API 调用](#api 调用)
3. [实时监控](#实时监控)
4. [导出告警](#导出告警)
5. [告警过滤](#告警过滤)

---

## 命令行查看

### 查看最近告警

```bash
# 查看最近 10 条告警
npm run alert recent

# 查看最近 20 条告警
npm run alert recent 20
```

**输出示例：**
```
🚨 最近 10 条告警:

1. [2026-03-07T13:30:00.000Z] file:/test/malicious.txt
   风险评分：0.8
   操作：BLOCKED

2. [2026-03-07T13:29:00.000Z] tool:shell
   风险评分：0.6
   操作：REDACTED
```

---

### 查看告警统计

```bash
npm run alert stats
```

**输出示例：**
```
🚨 安全告警报告
═══════════════════════════════════════
统计时间：2026-03-07T13:30:00.000Z
时间范围：2026-03-07T12:00:00.000Z - 2026-03-07T13:30:00.000Z

总告警数：156

按类型统计:
  PROMPT_INJECTION: 45 次
  DATA_EXFILTRATION: 32 次
  COMMAND_EXECUTION: 28 次
  SENSITIVE_DATA: 51 次

按严重程度统计:
  LOW: 23 次
  MEDIUM: 67 次
  HIGH: 54 次
  CRITICAL: 12 次

按操作统计:
  ALLOWED: 1234 次
  REDACTED: 89 次
  BLOCKED: 67 次

最近 5 条告警:
1. [2026-03-07T13:30:00.000Z] file:/test/malicious.txt
   风险评分：0.8
   风险数量：2
   操作：BLOCKED
   - COMMAND_EXECUTION (CRITICAL)
   - DATA_EXFILTRATION (HIGH)
...
═══════════════════════════════════════
```

---

### 搜索告警

```bash
# 搜索包含特定关键词的告警
npm run alert search rm
npm run alert search "prompt injection"
npm run alert search BLOCKED
```

---

### 导出告警数据

```bash
# 导出 JSON 格式
npm run alert export json > alerts.json

# 导出 CSV 格式
npm run alert export csv > alerts.csv
```

---

### 实时监控告警

```bash
# 开始实时监控（每 3 秒检查一次）
npm run alert monitor
```

**输出示例：**
```
👁️  开始实时监控告警...（按 Ctrl+C 停止）

🚨 新告警 [2026-03-07T13:30:00.000Z]
   事件：file:/test/malicious.txt
   风险评分：0.8
   操作：BLOCKED
   风险：COMMAND_EXECUTION(CRITICAL), DATA_EXFILTRATION(HIGH)

🚨 新告警 [2026-03-07T13:30:05.000Z]
   事件：tool:shell
   风险评分：0.6
   操作：REDACTED
   风险：SENSITIVE_DATA(HIGH)
```

按 `Ctrl+C` 停止监控。

---

## API 调用

### 在代码中使用

```typescript
import { plugin } from './runtime-security-guard';
import { AlertViewer } from './utils/alert-viewer';

// 创建告警查看器
const viewer = new AlertViewer((plugin as any).alerter);

// 获取最近告警
const recentAlerts = await viewer.getRecentAlerts(10);
console.log(recentAlerts);

// 获取告警统计
const stats = await viewer.getAlertStats();
console.log(stats);

// 搜索告警
const searchResults = await viewer.searchAlerts('rm -rf');
console.log(searchResults);

// 过滤告警
const filtered = await viewer.filterAlerts({
  severity: 'CRITICAL',
  limit: 50,
});
console.log(filtered);

// 生成报告
const report = await viewer.generateReport();
console.log(report);

// 导出告警
const jsonData = await viewer.exportAlerts('json');
const csvData = await viewer.exportAlerts('csv');
```

---

## 实时监控

### 基本监控

```typescript
const stop = await viewer.startMonitoring((alert) => {
  console.log('🚨 新告警:', alert);
}, 3000); // 每 3 秒检查一次

// 停止监控
stop();
```

### 高级监控（带过滤）

```typescript
const stop = await viewer.startMonitoring((alert) => {
  // 只处理 CRITICAL 级别告警
  if (alert.result?.risks?.some(r => r.severity === 'CRITICAL')) {
    console.log('🚨 CRITICAL 告警:', alert);
    
    // 发送通知
    sendNotification({
      title: 'CRITICAL 安全告警',
      message: `事件：${alert.eventId}`,
      severity: 'CRITICAL',
    });
  }
}, 1000);
```

---

## 告警过滤

### 按类型过滤

```typescript
// 只看提示注入告警
const injectionAlerts = await viewer.filterAlerts({
  type: 'PROMPT_INJECTION',
  limit: 100,
});
```

### 按严重程度过滤

```typescript
// 只看 CRITICAL 级别告警
const criticalAlerts = await viewer.filterAlerts({
  severity: 'CRITICAL',
  limit: 50,
});
```

### 按时间范围过滤

```typescript
// 查看最近 1 小时的告警
const oneHourAgo = new Date(Date.now() - 60 * 60 * 1000);
const recentAlerts = await viewer.filterAlerts({
  startTime: oneHourAgo,
  limit: 1000,
});
```

### 组合过滤

```typescript
// 查看最近 1 小时内的 CRITICAL 级别提示注入告警
const oneHourAgo = new Date(Date.now() - 60 * 60 * 1000);
const alerts = await viewer.filterAlerts({
  type: 'PROMPT_INJECTION',
  severity: 'CRITICAL',
  startTime: oneHourAgo,
  limit: 100,
});
```

---

## 告警级别说明

| 级别 | 说明 | 响应建议 |
|------|------|----------|
| **CRITICAL** | 极高风险，立即威胁 | 立即阻止，人工审查 |
| **HIGH** | 高风险，可能威胁 | 阻止或脱敏，尽快审查 |
| **MEDIUM** | 中等风险，需要关注 | 脱敏处理，定期审查 |
| **LOW** | 低风险，轻微异常 | 记录日志，可选审查 |

---

## 告警类型说明

| 类型 | 说明 | 示例 |
|------|------|------|
| **PROMPT_INJECTION** | 提示注入攻击 | 越狱、隐藏指令 |
| **DATA_EXFILTRATION** | 数据外泄尝试 | 发送敏感数据 |
| **COMMAND_EXECUTION** | 恶意命令执行 | rm -rf、下载执行 |
| **SENSITIVE_DATA** | 敏感数据泄露 | API 密钥、密码 |
| **SOCIAL_ENGINEERING** | 社会工程学攻击 | 紧急操控、权威冒充 |
| **SUPPLY_CHAIN** | 供应链攻击 | 恶意依赖、构建脚本 |
| **ZERO_DAY** | 零日漏洞利用 | 内存破坏、代码执行 |
| **APT** | APT 攻击 | 侦察、持久化、横向移动 |
| **INSIDER_THREAT** | 内部威胁 | 异常访问、权限滥用 |

---

## 集成到监控系统

### Prometheus 指标导出

```typescript
import { collectDefaultMetrics, Registry } from 'prom-client';

const register = new Registry();
collectDefaultMetrics({ register });

// 安全告警指标
const securityAlerts = new Counter({
  name: 'security_alerts_total',
  help: 'Total number of security alerts',
  labelNames: ['type', 'severity', 'action'],
  registers: [register],
});

// 在告警时记录
viewer.startMonitoring((alert) => {
  for (const risk of alert.result?.risks || []) {
    securityAlerts.inc({
      type: risk.type,
      severity: risk.severity,
      action: alert.action,
    });
  }
});
```

### Slack 通知

```typescript
viewer.startMonitoring((alert) => {
  if (alert.result?.risks?.some(r => r.severity === 'CRITICAL')) {
    sendSlackNotification({
      channel: '#security-alerts',
      text: `🚨 CRITICAL 安全告警`,
      attachments: [{
        color: 'danger',
        fields: [
          { title: '事件', value: alert.eventId, short: true },
          { title: '风险评分', value: alert.result?.riskScore, short: true },
          { title: '操作', value: alert.action, short: true },
          { title: '风险', value: alert.result?.risks?.map(r => r.type).join(', '), short: false },
        ],
      }],
    });
  }
});
```

---

## 最佳实践

1. **定期检查告警统计** - 每天查看 `npm run alert stats`
2. **设置 CRITICAL 告警通知** - 实时监控 CRITICAL 级别告警
3. **定期导出告警数据** - 每周导出 CSV 进行归档分析
4. **建立告警响应流程** - 定义不同级别告警的响应流程
5. **定期审查告警规则** - 根据实际告警调整规则阈值

---

**最后更新：** 2026-03-07  
**版本：** v1.1.0