API Reference
The Ephor API is a REST API served under the base path /api/v1.
Interactive Documentation
The canonical API reference is the Swagger UI served by the application:
| URL | Description |
|---|---|
/api/v1/swagger-ui/index.html | Interactive Swagger UI |
/api/v1/api-docs | Raw OpenAPI specification (JSON) |
Swagger UI is enabled when the local Spring profile is active (default in development). In production, enable it via springdoc.api-docs.enabled=true and springdoc.swagger-ui.enabled=true.
Endpoints Overview
Authentication
| Method | Path | Description |
|---|---|---|
GET | /auth/me | Current user identity, groups, and permissions |
GET | /auth/status | Authentication status |
GET | /auth/config | Client-facing auth config (login/logout URLs, provider) |
GET | /auth/logout | Logout URL |
Vulnerabilities
| Method | Path | Description |
|---|---|---|
GET | /vulnerabilities | List findings with filtering, sorting, and pagination |
GET | /vulnerabilities/{id} | Get a single vulnerability |
PATCH | /vulnerabilities/{id}/status | Change the status of a finding |
GET | /vulnerabilities/{id}/comments | List comments |
POST | /vulnerabilities/{id}/comments | Add a comment |
POST | /vulnerabilities/{id}/reopen | Reopen an auto-resolved finding |
POST | /vulnerabilities/auto-resolve | Resolve findings absent from recent scans |
Filtering and sorting
GET /vulnerabilities accepts these query parameters in addition to severity, status, namespace, search, page, and limit. Parameter names are camelCase.
| Parameter | Type | Description |
|---|---|---|
sortBy | string | priority (default), epss, severity, first_detected, last_seen, or cve_id |
sortOrder | string | asc or desc |
kevOnly | boolean | Only findings listed in CISA KEV |
deployedOnly | boolean | Only findings currently present in the cluster (status open or triaged) |
fixableOnly | boolean | Only findings with a fixed version available |
minEpss | number | Only findings with an EPSS score at or above this value (0–1) |
Each finding in the response carries its enrichment and priority data: kev_listed, kev_date_added, epss_score, epss_percentile, and the derived priority_tier (P0–P3). See Prioritization for how tiers are computed.
Escalations
| Method | Path | Description |
|---|---|---|
GET | /escalations | List escalations |
POST | /escalations | Create an escalation |
GET | /escalations/{id} | Get a single escalation |
PUT | /escalations/{id} | Update an escalation |
Triage
| Method | Path | Description |
|---|---|---|
GET | /triage | List triage records |
POST | /triage | Create a triage entry |
PUT | /triage/{id} | Update a triage entry |
GET | /triage/{id}/comments | List comments |
POST | /triage/{id}/comments | Add a comment |
Remediations
| Method | Path | Description |
|---|---|---|
GET | /remediations | List remediation records |
POST | /remediations | Create a remediation |
GET | /remediations/{id} | Get a single remediation |
PUT | /remediations/{id} | Update a remediation |
Dashboard
| Method | Path | Description |
|---|---|---|
GET | /dashboard/metrics | Aggregate counts by severity, status, and priority tier, plus action_now (P0 + P1) |
GET | /dashboard/trends | Finding counts over time |
GET | /dashboard/namespaces | List of namespaces with findings |
GET | /dashboard/namespace-comparison | Per-namespace severity breakdown |
GET | /dashboard/namespace-priority | Per-namespace priority-tier breakdown (P0–P3) |
Scan Ingestion
| Method | Path | Description |
|---|---|---|
POST | /scans/ingest | Ingest a vulnerability scan report |
Authentication
All endpoints except /auth/status and /auth/config require a valid authenticated session. Requests without proper identity headers receive a 401 Unauthorized response.
Detailed Reference
For full request/response schemas, query parameters, and error codes, use the interactive Swagger UI or download the OpenAPI spec from /api/v1/api-docs.