RHEcosystemAppEng/sast-ai-orchestrator
GitHub: RHEcosystemAppEng/sast-ai-orchestrator
这是一个基于REST API的SAST安全扫描编排器，用于在OpenShift环境中调度、监控并管理AI驱动的静态分析工作流。
Stars: 2 | Forks: 1
# SAST-AI-Orchestrator
[](https://sonarcloud.io/summary/new_code?id=RHEcosystemAppEng_sast-ai-orchestrator)
[](https://sonarcloud.io/summary/new_code?id=RHEcosystemAppEng_sast-ai-orchestrator)
[](https://sonarcloud.io/summary/new_code?id=RHEcosystemAppEng_sast-ai-orchestrator)
[](https://sonarcloud.io/summary/new_code?id=RHEcosystemAppEng_sast-ai-orchestrator)
[](https://sonarcloud.io/summary/new_code?id=RHEcosystemAppEng_sast-ai-orchestrator)
[](https://github.com/RHEcosystemAppEng/sast-ai-orchestrator/actions/workflows/codeql.yml)
[](https://github.com/RHEcosystemAppEng/sast-ai-orchestrator/actions/workflows/build-dev-image.yml)
管理 [SAST-AI-Workflow](https://github.com/RHEcosystemAppEng/sast-ai-workflow) 安全扫描 Red Hat OpenShift pipelines 的 Orchestrator REST API。
## API 端点
### 健康与监控
#### `GET /api/v1/health`
**描述：** 应用程序健康状态及依赖项检查
**响应：** `200 OK` / `503 Service Unavailable`
```
{
"status": "UP|DOWN",
"timestamp": "2025-01-01T10:00:00",
"version": "1.0.0",
"dependencies": {
"database": "UP",
"tekton": "UP",
"google-service-account": "UP - Service account available"
}
}
```
### 作业管理
#### `POST /api/v1/jobs/simple`
**描述：** 创建新的安全扫描作业
**请求体：**
```
{
"packageNvr": "package-name-version-release",
"inputSourceUrl": "https://example.com/source.zip",
"submittedBy": "user@example.com", # (optional, defaults to "unknown")
"useKnownFalsePositiveFile": false # (optional)
}
```
**响应：** `201 Created`
```
{
"jobId": 123,
"packageName": "package-name",
"packageNvr": "package-name-version-release",
"sourceCodeUrl": "https://example.com/source.zip",
"status": "PENDING",
"createdAt": "2025-01-01T10:00:00",
"startedAt": null,
"completedAt": null,
"cancelledAt": null,
"tektonUrl": null,
"batchId": null,
"projectName": "package-name",
"projectVersion": "version-release",
"oshScanId": null,
"jiraLink": null,
"hostname": null
}
```
#### `GET /api/v1/jobs`
**描述：** 列出所有作业，支持过滤和分页
**查询参数：**
- `packageName`（可选）：按包名称过滤
- `status`（可选）：按状态过滤（`PENDING`、`SCHEDULED`、`RUNNING`、`COMPLETED`、`FAILED`、`CANCELLED`）
- `page`（可选，默认值：0）：页码
- `size`（可选，默认值：20）：每页大小
**响应：** `200 OK`
```
[
{
"jobId": 123,
"packageName": "package-name",
"packageNvr": "package-name-version-release",
"sourceCodeUrl": "https://example.com/source.zip",
"status": "COMPLETED",
"createdAt": "2025-01-01T10:00:00",
"startedAt": "2025-01-01T10:05:00",
"completedAt": "2025-01-01T10:30:00",
"tektonUrl": "https://console-openshift-console.apps.appeng.clusters.se-apps.redhat.com/k8s/ns/sast-ai/tekton.dev~v1~PipelineRun/sast-ai-workflow-pipeline-123/",
"batchId": null,
"projectName": "package-name",
"projectVersion": "version-release",
"oshScanId": "scan-123",
"jiraLink": "https://jira.example.com/browse/ISSUE-123",
"hostname": "worker-node-1"
}
]
```
#### `GET /api/v1/jobs/{jobId}`
**描述：** 获取特定作业详情
**响应：** `200 OK` - 结构与作业创建响应相同
**错误响应：**
- `404 Not Found` - 未找到作业
#### `POST /api/v1/jobs/{jobId}/cancel`
**描述：** 取消正在运行的作业
**响应：** `200 OK`
```
"Job cancellation requested"
```
**错误响应：**
- `404 Not Found` - 未找到作业
- `400 Bad Request` - 无法取消作业（已完成/失败）
### 作业批次
#### `POST /api/v1/job-batches`
**描述：** 从 Google Sheets 提交批处理作业
**请求体：**
```
{
"batchGoogleSheetUrl": "https://docs.google.com/spreadsheets/d/...",
"submittedBy": "user@example.com", # (optional, defaults to "unknown")
"useKnownFalsePositiveFile": false # (optional)
}
```
**响应：** `201 Created`
```
{
"batchId": 456,
"batchGoogleSheetUrl": "https://docs.google.com/spreadsheets/d/...",
"submittedBy": "user@example.com",
"submittedAt": "2025-01-01T10:00:00",
"status": "PROCESSING",
"totalJobs": 10,
"completedJobs": 0,
"failedJobs": 0
}
```
#### `GET /api/v1/job-batches`
**描述：** 列出作业批次，支持分页
**查询参数：**
- `page`（可选，默认值：0）：页码
- `size`（可选，默认值：20）：每页大小
**响应：** `200 OK` - 批次对象数组（结构与批次创建响应相同）
#### `GET /api/v1/job-batches/{batchId}`
**描述：** 获取批次详情
**响应：** `200 OK` - 结构与批次创建响应相同
**错误响应：**
- `404 Not Found` - 未找到批次
#### `POST /api/v1/job-batches/{batchId}:cancel`
**描述：** 取消作业批次
**响应：** `200 OK`
```
"Job batch cancellation requested"
```
**错误响应：**
- `404 Not Found` - 未找到批次
### MLOps 批次
MLOps 批次端点支持对从 DVC (Data Version Control) 获取的多个 NVR (Name-Version-Release) 进行自动化测试。这些端点独立于常规作业批次，专为 MLOps 工作流设计。
#### `POST /api/v1/mlops-batch`
**描述：** 提交 MLOps 批次进行处理。从 DVC 获取 NVR 列表，并为每个具有指定 MLOps 参数的 NVR 创建单独的作业。
**请求体：**
```
{
"testingDataNvrsVersion": "1.0",
"promptsVersion": "1.0",
"knownNonIssuesVersion": "1.0",
"sastAiImage": "quay.io/ecosystem-appeng/sast-ai-workflow:latest",
"submittedBy": "user@example.com"
}
```
**字段：**
- `testingDataNvrsVersion`（必填）：用于获取测试 NVR 的 DVC 版本标签
- `promptsVersion`（必填）：prompts 配置的 DVC 版本
- `knownNonIssuesVersion`（必填）：已知非问题数据的 DVC 版本
- `sastAiImage`（必填）：SAST AI workflow 的容器镜像
- `submittedBy`（可选）：提交批次的人员或系统
**响应：** `201 Created`
```
{
"batchId": 123,
"testingDataNvrsVersion": "1.0",
"promptsVersion": "1.0",
"knownNonIssuesVersion": "1.0",
"sastAiImage": "quay.io/ecosystem-appeng/sast-ai-workflow:latest",
"submittedBy": "user@example.com",
"submittedAt": "2025-01-01T10:00:00",
"status": "PROCESSING",
"totalJobs": 0,
"completedJobs": 0,
"failedJobs": 0,
"lastUpdatedAt": "2025-01-01T10:00:00"
}
```
**错误响应：**
- `400 Bad Request` - 请求体无效或 DVC 获取失败
#### `GET /api/v1/mlops-batch`
**描述：** 列出所有 MLOps 批次，支持分页
**查询参数：**
- `page`（可选，默认值：0）：页码
- `size`（可选，默认值：20）：每页大小
**响应：** `200 OK` - MLOps 批次对象数组（结构与批次创建响应相同）
#### `GET /api/v1/mlops-batch/{batchId}`
**描述：** 获取特定 MLOps 批次详情
**响应：** `200 OK` - 结构与批次创建响应相同
**错误响应：**
- `404 Not Found` - 未找到 MLOps 批次
#### `GET /api/v1/mlops-batch/{batchId}/detailed`
**描述：** 获取详细的 MLOps 批次信息，包括所有作业及其指标
**响应：** `200 OK`
```
{
"batchId": 123,
"testingDataNvrsVersion": "1.0",
"promptsVersion": "1.0",
"knownNonIssuesVersion": "1.0",
"sastAiImage": "quay.io/ecosystem-appeng/sast-ai-workflow:latest",
"submittedBy": "user@example.com",
"submittedAt": "2025-01-01T10:00:00",
"status": "COMPLETED_WITH_ERRORS",
"totalJobs": 5,
"completedJobs": 3,
"failedJobs": 2,
"lastUpdatedAt": "2025-01-01T11:00:00",
"jobs": [
{
"jobId": 456,
"packageNvr": "acl-2.3.2-1.el10",
"packageName": "acl",
"projectName": "acl",
"projectVersion": "2.3.2-1",
"packageSourceCodeUrl": "https://download.devel.redhat.com/brewroot/vol/rhel-10/packages/acl/2.3.2/1.el10/src/acl-2.3.2-1.el10.src.rpm",
"knownFalsePositivesUrl": "https://gitlab.cee.redhat.com/osh/known-false-positives/-/raw/master/acl/ignore.err",
"status": "COMPLETED",
"createdAt": "2025-01-01T10:00:00",
"startedAt": "2025-01-01T10:01:00",
"completedAt": "2025-01-01T10:30:00",
"tektonUrl": "https://console-openshift-console.apps.appeng.clusters.se-apps.redhat.com/k8s/ns/sast-ai/tekton.dev~v1~PipelineRun/sast-ai-workflow-pipeline-456/",
"metrics": {
"accuracy": 0.95,
"precision": 0.87,
"recall": 0.92,
"f1Score": 0.89,
"confusionMatrix": {
"tp": 10,
"fp": 2,
"tn": 8,
"fn": 1
}
}
}
]
}
```
**错误响应：**
- `404 Not Found` - 未找到 MLOps 批次
### 包分析
#### `GET /api/v1/packages`
**描述：** 列出包漏洞摘要，支持分页
**查询参数：**
- `page`（可选，默认值：0）：页码
- `size`（可选，默认值：50）：每页大小
**响应：** `200 OK`
```
[
{
"packageName": "example-package",
"totalAnalyses": 25,
"lastAnalysisDate": "2025-01-01T10:00:00",
"completedAnalyses": 20,
"failedAnalyses": 2,
"runningAnalyses": 3
}
]
```
#### `GET /api/v1/packages/{packageName}`
**描述：** 获取特定包摘要
**响应：** `200 OK` - 结构与包列表项相同
#### `GET /api/v1/packages/{packageName}/jobs`
**描述：** 获取特定包的作业
**查询参数：**
- `page`（可选，默认值：0）：页码
- `size`（可选，默认值：20）：每页大小
**响应：** `200 OK` - 作业对象数组（结构与 `/api/v1/jobs` 响应相同）
### 状态值
**作业状态：**
- `PENDING` - 作业已创建但尚未调度
- `SCHEDULED` - 作业已调度执行
- `RUNNING` - 作业正在执行
- `COMPLETED` - 作业成功完成
- `FAILED` - 作业执行失败
- `CANCELLED` - 作业已取消
**批次状态：**
- `PROCESSING` - 批次正在处理中
- `COMPLETED` - 所有作业成功完成
- `COMPLETED_WITH_ERRORS` - 批次已完成，但部分作业失败
- `COMPLETED_EMPTY` - 批次已完成，但不包含有效作业
- `FAILED` - 批次处理失败
- `CANCELLED` - 批次已取消
### 附加说明
- multipart form 端点 `POST /api/v1/jobs` 存在但尚未实现 - 请改用 `/simple` 端点
- 所有时间戳均采用 ISO 8601 格式
- 所有端点返回带有适当 HTTP 状态码的 JSON 响应
- 错误响应包含响应体中的描述性错误消息
## 快速开始
### 本地开发
1. **克隆仓库**
git clone https://github.com/RHEcosystemAppEng/sast-ai-orchestrator.git
cd sast-ai-orchestrator
2. **设置 PostgreSQL**
# 使用 Docker
docker run --name postgres \
-e POSTGRES_DB=sast-ai \
-e POSTGRES_USER=quarkus \
-e POSTGRES_PASSWORD=quarkus \
-p 5432:5432 \
-d postgres:13
3. **运行应用程序**
./mvnw quarkus:dev
4. **访问 API**
http://localhost:8080/api/v1/health
## 部署
### 环境策略
该项目支持两种部署环境：
- **开发环境** (`sast-ai-dev` namespace):
- 使用 `latest` 容器镜像
- 每次 main 分支推送时自动更新
- 启用调试日志和宽松的资源限制
- **生产环境** (`sast-ai-prod` namespace):
- 使用带有发布标签的容器镜像（例如 `v1.0.1`）
- 仅在 GitHub release 时更新
- 生产级资源分配和日志记录
### 快速部署
```
# 开发环境
cd deploy
make deploy-dev
# 生产环境
cd deploy
make deploy-prod
# 检查部署状态
make status
```
### 容器镜像
- **开发环境**: `quay.io/ecosystem-appeng/sast-ai-orchestrator:latest`
- **生产环境**: `quay.io/ecosystem-appeng/sast-ai-orchestrator:v1.0.x`
### 手动构建开发镜像
**Build Dev Image** workflow 支持通过 GitHub Actions UI 手动触发，允许开发人员从任何分支构建并推送开发镜像。
**触发手动构建：**
1. 导航至 **Actions** → **Build Dev Image** → **Run workflow**
2. 选择要构建的分支
3. 配置选项：
- **Image tag**: 自定义标签（默认为分支名称，main 分支默认为 `latest`）
- **Push image**: 切换是否推送到 registry（默认：true）
**使用场景：**
- 合并前测试功能分支镜像
- 构建带有自定义标签的镜像以进行特定测试场景
- 仅构建不推送以验证构建过程
**注意事项：**
- 手动 dispatch 需要经过 `dev-image-builds` 环境批准
- `latest` 标签预留给 main 分支构建，不能用于手动 dispatch
- 包含 `/` 的分支名称在标签中会转换为 `-`（例如 `feature/foo` → `feature-foo`）
### Docker 部署
```
# 开发环境
docker run -p 8080:8080 quay.io/ecosystem-appeng/sast-ai-orchestrator:latest
# 生产环境
docker run -p 8080:8080 quay.io/ecosystem-appeng/sast-ai-orchestrator:v1.0.1
```
### Kubernetes 部署
- **Helm Chart**: 请参阅 `deploy/sast-ai-chart/` 进行 Helm 部署
- **ArgoCD**: 请参阅 `deploy/argocd/` 进行 GitOps 部署
- **文档**: 在 `deploy/` 目录中使用 `make help` 查看可用命令
### 特定环境访问
部署后，通过 OpenShift routes 访问应用程序：
```
# 获取生产环境的 route URL
kubectl get route sast-ai-orchestrator-prod -n sast-ai-prod
# 获取开发环境的 route URL
kubectl get route sast-ai-orchestrator-dev -n sast-ai-dev
# 通过 route 直接访问 API
curl https:///api/v1/health
```
## 配置
`application.properties` 中的关键配置选项：
```
# 数据库
quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/sast-ai
quarkus.datasource.username=quarkus
quarkus.datasource.password=quarkus
# Workflow Integration
sast.ai.workflow.namespace=sast-ai
quarkus.kubernetes-client.trust-certs=false
```
标签：AI, API, CodeQL, DevSecOps, NIDS, OpenShift, Red Hat, REST API, SAST, SonarQube, 上游代理, 人工智能, 域名枚举, 安全扫描, 安全评估工具, 容器化, 工作流, 控制器, 时序注入, 测试用例, 用户模式Hook绕过, 监控, 盲注攻击, 管道, 编排器, 自动化代码审查, 请求拦截, 调度, 静态应用安全测试