Applications and scans

Available since v0.0.2

Groups

Groups are logical containers for organizing applications (e.g., backend-services, frontend-apps).

POST /api/groups
Content-Type: application/json

{
  "name": "Backend Services",
  "path": "backend-services"
}

Parameter	Description
name	Display name
path	Unique URL path (used in group-based endpoints)

Applications

Applications represent the projects or services you monitor. Each application belongs to a group and has:

• Name - display name
• Slug - unique identifier within its group
• API token - auto-generated; used for CI/CD scan ingestion
• Repository URL - optional link to the source repository
• Asset criticality - low, medium, high, or critical

Create an application

POST /api/applications
Content-Type: application/json

{
  "name": "My Web App",
  "slug": "my-web-app",
  "group_id": 1
}

API token

Each application is issued an auto-generated token at creation. Use it to authenticate scan uploads from CI/CD:

curl -X POST https://servasec.local/api/ingest \
  -H "X-Api-Token: $APP_API_TOKEN" \
  -F "[email protected]"

Tokens can be regenerated from the application detail page or via API:

POST /api/applications/{id}/regenerate-token

Application versions

Versions let you track findings across different releases or environments (e.g., main, v1.0.0, staging).

POST /api/applications/{id}/versions
Content-Type: application/json

{
  "name": "v1.0.0",
  "branch": "main",
  "tag": "v1.0.0"
}

Compare versions

Compare findings between two versions to see what's new, fixed, or still present:

GET /api/applications/{id}/versions/compare?from=1.0&to=1.1

Scans

A scan represents a single upload of scanner results. Each scan contains:

• Scanner type - auto-detected from the file format
• Status - pending, processing, completed, or failed
• Version - the application version targeted
• Findings - the parsed vulnerabilities

Ingest results

Point any CI/CD pipeline at the ingest endpoint:

curl -X POST https://servasec.local/api/ingest \
  -H "X-Api-Token: $APP_API_TOKEN" \
  -F "[email protected]" \
  -F "version=v1.0.0"

The ingest flow:

1. Application is identified (via X-Api-Token, path parameter, or middleware context)
2. Version is created or updated
3. Scanner type is auto-detected
4. File is parsed
5. Findings are created with deduplication
6. Risk scores are calculated
7. Policies are evaluated
8. Webhooks are triggered

Authenticated application ingest

Authenticated requests can target an application by its numeric ID:

curl -X POST https://servasec.local/api/applications/1/ingest \
  -H "X-Api-Key: $API_KEY" \
  -F "[email protected]" \
  -F "version=staging"

This route requires API key authentication (not the application token) and write permission on the target application.

Group-scoped ingest

Applications can also be targeted by their group ID and slug:

curl -X POST https://servasec.local/api/groups/1/applications/my-web-app/ingest \
  -H "X-Api-Key: $API_KEY" \
  -F "[email protected]"

List scans

GET /api/scans?applicationId=1

Scan detail

GET /api/scans/{id}