Configuration Reference
Ephor follows the 12-factor app methodology. All runtime configuration is provided through environment variables.
Database
| Variable | Default | Description |
|---|---|---|
SPRING_DATASOURCE_URL | jdbc:postgresql://localhost:5432/ephor | JDBC connection URL |
SPRING_DATASOURCE_USERNAME | ephor | Database username |
SPRING_DATASOURCE_PASSWORD | ephor | Database password |
Ephor requires PostgreSQL. Other databases are not supported.
Authentication
| Variable | Default | Description |
|---|---|---|
AUTH_ENABLED | true | Enable authentication enforcement |
AUTH_DEV_ENABLED | false | Bypass authentication with a development user. Never enable in production. |
AUTH_PROVIDER | oauth2-proxy | Authentication provider |
AUTH_LOGIN_URL | /oauth2/start | Redirect URL for unauthenticated users |
AUTH_LOGOUT_URL | /oauth2/sign_out | Redirect URL after logout |
Development User
Only effective when AUTH_DEV_ENABLED=true.
| Variable | Default | Description |
|---|---|---|
AUTH_DEV_USERNAME | dev-user | Username for the development user |
AUTH_DEV_EMAIL | dev@localhost | Email for the development user |
AUTH_DEV_GROUPS | ephor-admins,developers,security-team | Comma-separated groups |
AUTH_DEV_DISPLAY_NAME | Development User | Display name |
User Directory
| Variable | Default | Description |
|---|---|---|
EPHOR_USER_DIRECTORY_PROVIDER | internal | Provider for user/group sync. Options: internal, keycloak, github, none |
Keycloak Provider
Used when EPHOR_USER_DIRECTORY_PROVIDER=keycloak.
| Variable | Description |
|---|---|
KEYCLOAK_SERVER_URL | Base URL of the Keycloak server |
KEYCLOAK_REALM | Keycloak realm name |
KEYCLOAK_CLIENT_ID | Client ID for API access |
KEYCLOAK_CLIENT_SECRET | Client secret for API access |
KEYCLOAK_SYNC_INTERVAL | Sync interval in milliseconds (default: 900000 / 15 minutes) |
The Keycloak service account needs the following realm roles: view-users, manage-users, query-users, query-groups, query-realms.
GitHub Provider
Used when EPHOR_USER_DIRECTORY_PROVIDER=github.
| Variable | Description |
|---|---|
GITHUB_ORG | GitHub organization name |
GITHUB_TOKEN | Personal access token with read:org scope |
GITHUB_SYNC_INTERVAL | Sync interval in milliseconds (default: 1800000 / 30 minutes) |
Team-to-group mappings are configured via Spring Boot relaxed binding. By default, GitHub team slugs are used directly as group names.
Enrichment
Ephor enriches findings with exploitation data from two public feeds: the CISA Known Exploited Vulnerabilities (KEV) catalog and FIRST EPSS scores. This data drives priority tiers. The feeds are pulled on a schedule by the API; nothing is sent outbound except the feed requests themselves.
| Variable | Default | Description |
|---|---|---|
EPHOR_ENRICHMENT_ENABLED | true | Enable the KEV/EPSS enrichment scheduler |
EPHOR_ENRICHMENT_KEV_URL | CISA KEV catalog | Source URL for the KEV catalog (JSON) |
EPHOR_ENRICHMENT_EPSS_URL | FIRST EPSS scores | Source URL for the daily EPSS scores (gzipped CSV) |
EPHOR_ENRICHMENT_REFRESH_INTERVAL | 86400000 | Time between refreshes, in milliseconds (default: 1 day) |
EPHOR_ENRICHMENT_INITIAL_DELAY | 30000 | Delay before the first run after startup, in milliseconds |
EPHOR_ENRICHMENT_EPSS_THRESHOLD | 0.10 | EPSS probability at or above which a CVE counts as exploitable |
A failed feed refresh leaves the previously stored values in place, so a transient outage does not blank out enrichment data. Findings with no CVE ID (some GHSA-only advisories) are not matched by either feed. For air-gapped installs, point the URLs at an internal mirror of the two feeds.
Logging
| Variable | Default | Description |
|---|---|---|
LOGGING_STRUCTURED_FORMAT_CONSOLE | (none) | Set to ecs or logstash for structured JSON logging. Leave unset for human-readable output. |
Server
| Variable | Default | Description |
|---|---|---|
PORT | 8080 | Port the API listens on |