SAST-AI-Orchestrator

Java Quarkus REST API that manages SAST-AI-Workflow security scanning Tekton pipelines.

API Endpoints

Health & Monitoring

`GET /api/v1/health`

Description: Application health status with dependency checks

Response: 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"
  }
}

Job Management

`POST /api/v1/jobs/simple`

Description: Create a new security scanning job

Request Body:

{
  "packageNvr": "package-name-version-release",
  "inputSourceUrl": "https://example.com/source.zip",
  "submittedBy": "user@example.com", # (optional, defaults to "unknown")
  "useKnownFalsePositiveFile": false # (optional)
}

Response: 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`

Description: List all jobs with filtering and pagination

Query Parameters:

packageName (optional): Filter by package name
status (optional): Filter by status (PENDING, SCHEDULED, RUNNING, COMPLETED, FAILED, CANCELLED)
page (optional, default: 0): Page number
size (optional, default: 20): Page size

Response: 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://tekton.example.com/pipelineruns/job-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}`

Description: Get specific job details

Response: 200 OK - Same structure as job creation response Error Responses:

404 Not Found - Job not found

`POST /api/v1/jobs/{jobId}/cancel`

Description: Cancel a running job

Response: 200 OK

"Job cancellation requested"

Error Responses:

404 Not Found - Job not found
400 Bad Request - Job cannot be cancelled (already completed/failed)

Job Batches

`POST /api/v1/job-batches`

Description: Submit batch processing jobs from Google Sheets

Request Body:

{
  "batchGoogleSheetUrl": "https://docs.google.com/spreadsheets/d/...",
  "submittedBy": "user@example.com", # (optional, defaults to "unknown")
  "useKnownFalsePositiveFile": false # (optional)
}

Response: 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`

Description: List job batches with pagination

Query Parameters:

page (optional, default: 0): Page number
size (optional, default: 20): Page size

Response: 200 OK - Array of batch objects (same structure as batch creation response)

`GET /api/v1/job-batches/{batchId}`

Description: Get batch details

Response: 200 OK - Same structure as batch creation response Error Responses:

404 Not Found - Batch not found

`POST /api/v1/job-batches/{batchId}:cancel`

Description: Cancel a job batch

Response: 200 OK

"Job batch cancellation requested"

Error Responses:

404 Not Found - Batch not found

MLOps Batch

MLOps batch endpoints enable automated testing of multiple NVRs (Name-Version-Release) fetched from DVC (Data Version Control). These endpoints are independent from regular job batches and designed specifically for ML operations workflows.

`POST /api/v1/mlops-batch`

Description: Submit MLOps batch for processing. Fetches NVR list from DVC and creates individual jobs for each NVR with specified MLOps parameters.

Request Body:

{
  "testingDataNvrsVersion": "1.0",
  "promptsVersion": "1.0",
  "knownNonIssuesVersion": "1.0",
  "sastAiImage": "quay.io/ecosystem-appeng/sast-ai-workflow:latest",
  "submittedBy": "user@example.com"
}

Fields:

testingDataNvrsVersion (required): DVC version tag for fetching test NVRs
promptsVersion (required): DVC version for prompts configuration
knownNonIssuesVersion (required): DVC version for known non-issues data
sastAiImage (required): Container image for SAST AI workflow
submittedBy (optional): User or system that submitted the batch

Response: 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"
}

Error Responses:

400 Bad Request - Invalid request body or DVC fetch failure

`GET /api/v1/mlops-batch`

Description: List all MLOps batches with pagination

Query Parameters:

page (optional, default: 0): Page number
size (optional, default: 20): Page size

Response: 200 OK - Array of MLOps batch objects (same structure as batch creation response)

`GET /api/v1/mlops-batch/{batchId}`

Description: Get specific MLOps batch details

Response: 200 OK - Same structure as batch creation response

Error Responses:

404 Not Found - MLOps batch not found

`GET /api/v1/mlops-batch/{batchId}/detailed`

Description: Get detailed MLOps batch information including all jobs and their metrics

Response: 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://tekton.example.com/pipelineruns/job-456",
      "metrics": {
        "accuracy": 0.95,
        "precision": 0.87,
        "recall": 0.92,
        "f1Score": 0.89,
        "confusionMatrix": {
          "tp": 10,
          "fp": 2,
          "tn": 8,
          "fn": 1
        }
      }
    }
  ]
}

Error Responses:

404 Not Found - MLOps batch not found

Package Analysis

`GET /api/v1/packages`

Description: List package vulnerability summaries with pagination

Query Parameters:

page (optional, default: 0): Page number
size (optional, default: 50): Page size

Response: 200 OK

[
  {
    "packageName": "example-package",
    "totalAnalyses": 25,
    "lastAnalysisDate": "2025-01-01T10:00:00",
    "completedAnalyses": 20,
    "failedAnalyses": 2,
    "runningAnalyses": 3
  }
]

`GET /api/v1/packages/{packageName}`

Description: Get specific package summary

Response: 200 OK - Same structure as package list item

`GET /api/v1/packages/{packageName}/jobs`

Description: Get jobs for a specific package

Query Parameters:

page (optional, default: 0): Page number
size (optional, default: 20): Page size

Response: 200 OK - Array of job objects (same structure as /api/v1/jobs response)

Status Values

Job Status:

PENDING - Job created but not yet scheduled
SCHEDULED - Job scheduled for execution
RUNNING - Job currently executing
COMPLETED - Job completed successfully
FAILED - Job failed during execution
CANCELLED - Job was cancelled

Batch Status:

PROCESSING - Batch is being processed
COMPLETED - All jobs completed successfully
COMPLETED_WITH_ERRORS - Batch completed but some jobs failed
COMPLETED_EMPTY - Batch completed but contained no valid jobs
FAILED - Batch processing failed
CANCELLED - Batch was cancelled

Additional Notes

The multipart form endpoint POST /api/v1/jobs exists but is not yet implemented - use /simple endpoint instead
All timestamps are in ISO 8601 format
All endpoints return JSON responses with appropriate HTTP status codes
Error responses include descriptive error messages in the response body

Quick Start

Local Development

Clone the repository

git clone https://github.com/RHEcosystemAppEng/sast-ai-orchestrator.git
cd sast-ai-orchestrator

Setup PostgreSQL

# Using Docker
docker run --name postgres \
-e POSTGRES_DB=sast-ai \
-e POSTGRES_USER=quarkus \
-e POSTGRES_PASSWORD=quarkus \
-p 5432:5432 \
-d postgres:13

Run the application
```
./mvnw quarkus:dev
```
Access the API
```
http://localhost:8080/api/v1/health
```

Deployment

Docker Deployment

# JVM Mode (Fast startup)
docker build -f src/main/docker/Dockerfile.jvm -t sast-ai-orchestrator:jvm .

Kubernetes Deployment

Helm Chart: See deploy/sast-ai-chart/ for Helm deployment
ArgoCD: See deploy/argocd/ for GitOps deployment
Documentation: Refer to deploy/README.md for detailed instructions

Configuration

Key configuration options in application.properties:

# Database
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

_{Built with ❤️ by the Red Hat Ecosystem App Engineering Team}

Name		Name	Last commit message	Last commit date
Latest commit History 366 Commits
.github		.github
.mvn/wrapper		.mvn/wrapper
deploy		deploy
githooks		githooks
grafana		grafana
src		src
.gitignore		.gitignore
IMPLEMENTED_SCHEMA.md		IMPLEMENTED_SCHEMA.md
LICENSE		LICENSE
README.md		README.md
lombok.config		lombok.config
mvnw		mvnw
mvnw.cmd		mvnw.cmd
pom.xml		pom.xml

License

RHEcosystemAppEng/sast-ai-orchestrator

Folders and files

Latest commit

History

Repository files navigation

SAST-AI-Orchestrator

API Endpoints

Health & Monitoring

GET /api/v1/health

Job Management

POST /api/v1/jobs/simple

GET /api/v1/jobs

GET /api/v1/jobs/{jobId}

POST /api/v1/jobs/{jobId}/cancel

Job Batches

POST /api/v1/job-batches

GET /api/v1/job-batches

GET /api/v1/job-batches/{batchId}

POST /api/v1/job-batches/{batchId}:cancel

MLOps Batch

POST /api/v1/mlops-batch

GET /api/v1/mlops-batch

GET /api/v1/mlops-batch/{batchId}

GET /api/v1/mlops-batch/{batchId}/detailed

Package Analysis

GET /api/v1/packages

GET /api/v1/packages/{packageName}

GET /api/v1/packages/{packageName}/jobs

Status Values

Additional Notes

Quick Start

Local Development

Deployment

Docker Deployment

Kubernetes Deployment

Configuration

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors 7

Uh oh!

Languages

`GET /api/v1/health`

`POST /api/v1/jobs/simple`

`GET /api/v1/jobs`

`GET /api/v1/jobs/{jobId}`

`POST /api/v1/jobs/{jobId}/cancel`

`POST /api/v1/job-batches`

`GET /api/v1/job-batches`

`GET /api/v1/job-batches/{batchId}`

`POST /api/v1/job-batches/{batchId}:cancel`

`POST /api/v1/mlops-batch`

`GET /api/v1/mlops-batch`

`GET /api/v1/mlops-batch/{batchId}`

`GET /api/v1/mlops-batch/{batchId}/detailed`

`GET /api/v1/packages`

`GET /api/v1/packages/{packageName}`

`GET /api/v1/packages/{packageName}/jobs`

Packages