Skip to content

API-INTEGRATION.md

Latest commit

 

History

History
290 lines (205 loc) · 6.5 KB

API-INTEGRATION.md

File metadata and controls

290 lines (205 loc) · 6.5 KB
Raw

VULNRΞPO API Integration Reference

This document describes the HTTP API that VULNRΞPO uses to communicate with an optional backend storage server. Implementing this API lets you store encrypted reports on your own infrastructure instead of (or in addition to) browser-local IndexedDB.

All report data sent to and from the API is AES-256-GCM encrypted ciphertext. Plaintext report content never leaves the browser.

Example Server

An example server implementation is available at: https://github.com/kac89/vulnrepo-server

Note: The example server is intended for personal or small-team use. Review and harden it before using in a production environment.

Authentication

All requests must include two custom HTTP headers:

Header Description
Vulnrepo-Auth Your API access key
Vulnrepo-Action The action to perform (see endpoints below)

Your server must also return the following CORS headers to allow requests from browser-hosted instances:

Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: vulnrepo-auth, vulnrepo-action

Endpoints

All requests use POST /api/.

apiconnect — Verify API key and retrieve account info

Request:

POST /api/ HTTP/2
Vulnrepo-Auth: <API-ACCESS-KEY>
Vulnrepo-Action: apiconnect

Response:

{
  "AUTH": "OK",
  "WELCOME": "John Doe",
  "CREATEDATE": "2021-05-14",
  "EXPIRYDATE": "2025-03-18",
  "CURRENT_STORAGE": "1000000",
  "MAX_STORAGE": "10000000"
}
Field Type Description
AUTH string "OK" on success
WELCOME string Display name for the account
CREATEDATE string Account creation date (YYYY-MM-DD)
EXPIRYDATE string Access expiry date (YYYY-MM-DD); optional
CURRENT_STORAGE string Bytes currently used on the server
MAX_STORAGE string Maximum storage quota in bytes

getreportslist — List all reports

Request:

POST /api/ HTTP/2
Vulnrepo-Auth: <API-ACCESS-KEY>
Vulnrepo-Action: getreportslist
Content-Type: application/x-www-form-urlencoded; charset=UTF-8

Response:

[
  {
    "report_id": "<report_id>",
    "report_name": "Test Report",
    "report_createdate": 1606571788759,
    "report_lastupdate": 1608657635687
  }
]
Field Type Description
report_id string Unique report identifier (UUID)
report_name string Human-readable report name
report_createdate number Unix timestamp (ms) of creation
report_lastupdate number Unix timestamp (ms) of last update

getreport — Retrieve a single report

Request:

POST /api/ HTTP/2
Vulnrepo-Auth: <API-ACCESS-KEY>
Vulnrepo-Action: getreport
Content-Type: application/x-www-form-urlencoded; charset=UTF-8

reportid=<report_id>

Request body parameters:

Parameter Type Description
reportid string Required. The ID of the report to retrieve

Response:

[
  {
    "report_id": "<report_id>",
    "report_name": "Test report",
    "report_createdate": 1616859952914,
    "report_lastupdate": "",
    "encrypted_data": "U2FsdGVkX1+t8fhgoP...[truncated]"
  }
]
Field Type Description
report_id string Report identifier
report_name string Report name
report_createdate number Unix timestamp (ms) of creation
report_lastupdate number | string Unix timestamp (ms) of last update, or "" if never updated
encrypted_data string Base64-encoded AES-256-GCM encrypted report data

savereport — Save a new report

Request:

POST /api/ HTTP/2
Vulnrepo-Auth: <API-ACCESS-KEY>
Vulnrepo-Action: savereport
Content-Type: application/x-www-form-urlencoded; charset=UTF-8

reportdata=<base64_encoded_report_json>

Request body parameters:

Parameter Type Description
reportdata string Required. Base64-encoded JSON containing the report object (including encrypted_data)

Success response:

{"REPORT_SAVED": "OK"}

Error response — no storage quota remaining:

{"STORAGE": "NOSPACE"}

updatereport — Update an existing report

Request:

POST /api/ HTTP/2
Vulnrepo-Auth: <API-ACCESS-KEY>
Vulnrepo-Action: updatereport
Content-Type: application/x-www-form-urlencoded; charset=UTF-8

reportdata=<base64_encoded_report_json>

Request body parameters:

Parameter Type Description
reportdata string Required. Base64-encoded JSON containing the updated report object

Success response:

{"REPORT_UPDATE": "OK"}

Error response — no storage quota remaining:

{"STORAGE": "NOSPACE"}

removereport — Delete a report

Request:

POST /api/ HTTP/2
Vulnrepo-Auth: <API-ACCESS-KEY>
Vulnrepo-Action: removereport
Content-Type: application/x-www-form-urlencoded; charset=UTF-8

reportid=<report_id>

Request body parameters:

Parameter Type Description
reportid string Required. The ID of the report to delete

Response:

{"REMOVE_REPORT": "OK"}

getreportprofiles — Retrieve report profiles

Report profiles store reusable configuration (logo, researcher info, theme, CSS).

Request:

POST /api/ HTTP/2
Vulnrepo-Auth: <API-ACCESS-KEY>
Vulnrepo-Action: getreportprofiles
Content-Type: application/x-www-form-urlencoded; charset=UTF-8

Response: JSON array of report profile objects.

getreporttemplates — Retrieve issue templates

Request:

POST /api/ HTTP/2
Vulnrepo-Auth: <API-ACCESS-KEY>
Vulnrepo-Action: getreporttemplates
Content-Type: application/x-www-form-urlencoded; charset=UTF-8

Response: JSON array of issue template objects.

Report Object Schema

The reportdata field sent in savereport and updatereport is a Base64-encoded JSON string with the following top-level structure:

{
  "report_id": "<uuid>",
  "report_name": "My Assessment",
  "report_createdate": 1616859952914,
  "report_lastupdate": 1616900000000,
  "encrypted_data": "<base64-encoded AES-256-GCM ciphertext>"
}

The encrypted_data field is a versioned binary blob encoded in Base64:

  • v2 format (current): [0x76, 0x32] + salt(16 bytes) + iv(12 bytes) + ciphertext
  • Legacy format: CryptoJS-compatible AES ciphertext (automatically detected for backward compatibility)