VulnerabilitiesCreate a vulnerability

Create a vulnerability

Creates a vulnerability finding. Findings created through the API always have source set to api, and you can't set it yourself. Use the vulnerabilityId returned in the response, not the one you sent, in later GET and PATCH calls.

  • Duplicate IDs: If a finding created through the API already has the same vulnerabilityId, the request returns 409 with the error code conflict and the existing finding doesn't change. This applies even when the existing finding is closed.
  • Each source is separate: A finding created through the API with the same ID as a finding imported from CSV is a new record, so api#VUL-1001 and import#VUL-1001 can both exist. Scrut doesn't merge findings across sources.
  • ID matching: Scrut matches IDs without regard to case and stores them in upper case in vulnerabilityId. For example, cve-2021-44228 is treated as CVE-2021-44228 and returned as api%23CVE-2021-44228.
  • No CVE lookup: Scrut doesn't fill in the title, description, CVSS score or severity from a CVE ID. Only cveId is set, in lower case, for example cve-2021-44228.
  • Closed on create: You can create a finding that's already closed by sending "status": "closed".
  • Lower-case storage: Scrut stores title and affected resource names in lower case. The Scrut app shows them in title case.
  • Changes after create: You can change only assigneeEmail, reportLink and customFields through the API. You can't change status, severity, title or affected resources. You can't close an existing finding through the API.
curl -X POST "https://api.scrut.io/v1/vulnerabilities" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -H "Authorization: Bearer YOUR_API_TOKEN (JWT)" \
  -d '{
  "vulnerabilityId": "VUL-5672",
  "title": "public s3 bucket",
  "description": "Bucket is world-readable.",
  "remediation": "Block public ACLs.",
  "stepsToReproduce": "Open the bucket URL.",
  "severity": "high",
  "status": "open",
  "fixAvailable": "no",
  "firstSeen": 1704067200000,
  "affectedResources": [
    {
      "name": "s3://bucket",
      "type": "s3",
      "tags": [
        "public",
        "prod"
      ]
    }
  ],
  "assigneeEmail": "jordan@example.com"
}'
{
  "data": {
    "vulnerabilityId": "api%23VUL-5672",
    "title": "public s3 bucket",
    "description": "Bucket is world-readable.",
    "status": "open",
    "severity": "high",
    "source": "api",
    "assignees": [
      {
        "name": "Jordan Kim",
        "email": "jordan@example.com",
        "isPrimary": true
      }
    ],
    "firstSeen": 1704067200000,
    "cveId": "",
    "remediation": "Block public ACLs.",
    "stepsToReproduce": "Open the bucket URL.",
    "customFields": []
  },
  "meta": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}
POST
/v1/vulnerabilities
POST
Base URLstring

Target server for requests. Edit to use your own host.

Bearer Token (JWT)
Bearer Tokenstring
Required

Machine access token from POST /oauth/token. Send Authorization: Bearer $SCRUT_ACCESS_TOKEN on every /v1 request.

Machine access token from POST /oauth/token. Send Authorization: Bearer $SCRUT_ACCESS_TOKEN on every /v1 request.
Content-Typestring
Required

The media type of the request body

Options: application/json
header
Idempotency-Keystring
Required

Client-generated key identifying one logical write. 1–128 characters; letters, numbers, and . _ ~ - only. Reuse the same key and body to retry safely. Reusing a key with a different body returns 409 idempotency_key_reused. Successful 2xx responses are replayed for 24 hours.

Min length: 1 • Max length: 128 • Pattern: ^[A-Za-z0-9._~-]{1,128}$
vulnerabilityIdstring
Required

A CVE ID, or VUL- followed by exactly four digits, for example VUL-5672. Any other format, such as GHSA-… or VUL-12345, returns 400. Matched without regard to case and stored in upper case. Scrut stores the finding as api#<vulnerabilityId> and returns it URL-encoded, for example api%23VUL-5672. Use the returned value as-is in GET and PATCH paths.

Pattern: ^([Vv][Uu][Ll]-\d{4}|[Cc][Vv][Ee]-\d{4}-(0\d{3}|[1-9]\d{3,}))$
titlestring
Required

Stored in lower case. The Scrut app shows it in title case.

descriptionstring
Max length: 750
remediationstring
Max length: 750
stepsToReproducestring
Max length: 750
severitystring
Required
Options: critical, high, medium, low
statusstring
Required

Send closed to create a finding that's already closed.

Options: open, closed, acknowledged
fixAvailablestring
Options: yes, no
firstSeeninteger

Unix epoch milliseconds.

Format: int64
affectedResourcesarray

Resources affected by the finding. Each resource needs a name and a type, and can have up to three tags. Scrut stores resource names in lower case.

assigneeEmailstring

Email address of a user in your Scrut organization. An invalid email address, or one that doesn't match a user in your organization, returns 400.

Format: email
Request Preview
Response

Response will appear here after sending the request

Authentication

header
Authorizationstring
Required

Bearer token (JWT). Machine access token from POST /oauth/token. Send Authorization: Bearer $SCRUT_ACCESS_TOKEN on every /v1 request.

Headers

Idempotency-Keystring
Required

Client-generated key identifying one logical write. 1–128 characters; letters, numbers, and . _ ~ - only. Reuse the same key and body to retry safely. Reusing a key with a different body returns 409 idempotency_key_reused. Successful 2xx responses are replayed for 24 hours.

Example:
7c9e6679-7425-40de-944b-e07fc1f90ae7

Body

application/json
vulnerabilityIdstring
Required

A CVE ID, or VUL- followed by exactly four digits, for example VUL-5672. Any other format, such as GHSA-… or VUL-12345, returns 400. Matched without regard to case and stored in upper case. Scrut stores the finding as api#<vulnerabilityId> and returns it URL-encoded, for example api%23VUL-5672. Use the returned value as-is in GET and PATCH paths.

Example:
VUL-5672
titlestring
Required

Stored in lower case. The Scrut app shows it in title case.

Example:
public s3 bucket
descriptionstring
Example:
Bucket is world-readable.
remediationstring
Example:
Block public ACLs.
stepsToReproducestring
Example:
Open the bucket URL.
severitystring
Required
Allowed values:criticalhighmediumlow
statusstring
Required

Send closed to create a finding that's already closed.

Allowed values:openclosedacknowledged
fixAvailablestring
Allowed values:yesno
firstSeeninteger

Unix epoch milliseconds.

Example:
1704067200000
affectedResourcesarray

Resources affected by the finding. Each resource needs a name and a type, and can have up to three tags. Scrut stores resource names in lower case.

assigneeEmailstring

Email address of a user in your Scrut organization. An invalid email address, or one that doesn't match a user in your organization, returns 400.

Example:
jordan@example.com

Responses