Name: Vulnerability Scanner API for Images, Repos and Code
Brand: codered
SKU: api-codered-vulnreport
Availability: InStock
Author: API Market

Mohaimenul Islam Mubin

# VulnReport: Container Image, Repo and Code Vulnerability Scanner API

## Overview

The VulnReport API scans container images, git repositories and uploaded codebases for known vulnerabilities and code-level security issues, and returns the results as structured JSON or a rendered PDF report. It runs two open-source scanners for you: Trivy checks images, repositories and archives against CVE databases (OS packages, language dependencies and misconfigurations), and Semgrep runs static analysis on repositories and uploaded code to catch issues such as hardcoded secrets, injection risks and insecure patterns. There is no scanner to install and no vulnerability database to keep up to date. `POST /scan` scans an image or a git repository, `POST /scan/upload` scans an archive of your own code, `GET /scan/jobs/{job_id}` returns the status and result of a scan that is still running, and `GET /scan/jobs/{job_id}/download` returns the PDF report for a scan run with `format=pdf`.

Scans can take a while, so every scan call accepts a `wait_seconds` query parameter. The API holds your request open for up to that many seconds and returns the finished result (`200`) if the scan completes in time; otherwise it returns `202` with a `job_id` to poll. Polls that find the scan still running are free. The API is built for DevOps and platform teams gating CI/CD pipelines, security engineers checking images before deployment, and developers vetting third-party code. Each JSON result carries a 0 to 100 risk score, a count of findings by severity, and a list of findings with the CVE or rule ID, the affected package or file location, the installed and fixed versions, and a short description.

## Features

*   **5 endpoints**: Scan an image or repository, scan an uploaded archive, poll a scan job, download a PDF report, and check service health.
*   **Three kinds of input**: A container image reference (`alpine:3.19`, or a private registry image with credentials), a git URL (GitHub, GitLab, Bitbucket or self-hosted, with an optional branch, tag or commit), or an archive of your own code (.zip, .tar, .tar.gz, .tgz, .tar.bz2 or .tbz2, up to 300MB).
*   **Two scanners**: Trivy for CVEs in OS packages and language dependencies (all scan types), and Semgrep static analysis for code-level issues (repository and upload scans).
*   **JSON or PDF output**: Get findings as JSON, or set `format=pdf` for a report you can hand to a non-technical reader. PDF reports accept a custom `report_title`.
*   **Risk score and summary**: Every result includes a 0 to 100 risk score and counts of critical, high, medium and low findings, so a CI step can gate on one number.
*   **Wait or poll**: `wait_seconds` (default 20, max 55) returns the result in the same call when the scan finishes in time, and falls back to a job ID to poll when it does not.
*   **Free polling**: A job poll that returns a still-running status is not billed. Only a call that returns a finished result counts as 1 call.
*   **Cached repeat scans**: Scanning an unchanged target returns the cached result straight away. Uploads are cached by the archive's SHA-256 hash. Requests that include credentials are never cached.
*   **Private targets**: Scan private registry images with `registry_username` and `registry_password`, and private repositories with `git_username` and `git_token`.
*   **Rate limit**: 2 requests per second on the Free, Pro and Bulk plans.

## Use Cases

*   **CI/CD gating**: Fail a build when a pushed image or repository has new CRITICAL or HIGH findings, using `risk_score` or the `summary` counts.
*   **Pre-deployment checks**: Scan an image before it goes to production without installing Trivy or Semgrep in your own pipeline.
*   **Vendor and dependency due diligence**: Point the API at a third-party image or repository before you adopt it.
*   **Private code audits**: Upload an archive of your own codebase, or scan a private repository with a read token, without making the code public.
*   **Client-facing reports**: Generate a PDF report to share with clients, auditors or managers as-is.

## API Documentation

### Base URL

All requests go through the API.market gateway at this base URL:

```
https://prod.api.market/api/v1/codered/vulnreport
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Scan a container image or git repository

Scans a container image (`scan_type: "image"`) or a git repository (`scan_type: "repo"`) and returns the findings. Image scans run Trivy. Repository scans shallow-clone the repository on the server and run Trivy and Semgrep against it. To scan your own code without a public repository, use Scan an uploaded codebase instead.

If the scan finishes within `wait_seconds`, the response is `200` with the job envelope (`job_id`, `status: "finished"` and `result`). A cache hit returns `200` straight away with the result object itself (`target`, `scan_type`, `risk_score`, `summary`, `findings`) and no job. If the scan is still running when the wait ends, the response is `202` with a `job_id` and a `status_url`; poll it with Get a scan job. With `format=pdf`, a scan that finishes within the wait returns the PDF file itself, so save the response body to a file.

**Method:** `POST`

**Endpoint:** `/scan`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `wait_seconds` | query | Seconds to hold the request open for the finished result before returning `202` with a job ID. Use `0` to get a job ID straight away. | number | No | `20` | `55` |
| `target` | body | The image reference (for example `alpine:3.19` or `registry.example.com/myorg/myapp:latest`) or the git repository URL. | string | Yes | - | - |
| `scan_type` | body | `image` for a container image, `repo` for a git repository. | string | No | `image` | - |
| `format` | body | `json` for findings in the response, `pdf` for a rendered report. | string | No | `json` | - |
| `report_title` | body | Title printed on the PDF report. Only used when `format` is `pdf`. | string | No | - | - |
| `branch` | body | Branch, tag or commit to check out. `repo` scans only. | string | No | - | - |
| `git_username` | body | Username for a private repository, where the git host needs one (for example GitLab, or `oauth2` with a GitHub token). `repo` scans only. | string | No | - | - |
| `git_token` | body | Access token for a private repository. `repo` scans only. Requests with a token are not cached. | string | No | - | - |
| `registry_username` | body | Username for a private container registry. `image` scans only. | string | No | - | - |
| `registry_password` | body | Password, personal access token or robot token for a private container registry. `image` scans only. Requests with a password are not cached. | string | No | - | - |

**Example Request:**

```bash
curl -X POST "https://prod.api.market/api/v1/codered/vulnreport/scan?wait_seconds=25" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target":"alpine:3.19","scan_type":"image","format":"json"}'
```

**Example Response (200 OK, abridged to 2 of 10 findings):**

```json
{
  "job_id": "c0febc3d-f7aa-4040-b4f7-84464118e1d6",
  "status": "finished",
  "result": {
    "target": "alpine:3.19",
    "scan_type": "image",
    "scan_date": "2026-09-16T16:35:03.630551Z",
    "risk_score": 23,
    "summary": {
      "critical": 0,
      "high": 2,
      "medium": 5,
      "low": 3
    },
    "total_findings": 10,
    "findings": [
      {
        "id": "CVE-2024-58251",
        "package": "busybox",
        "severity": "MEDIUM",
        "installed_version": "1.36.1-r20",
        "fixed_version": "1.36.1-r21",
        "description": "In netstat in BusyBox through 1.37.0, local users can launch of network application with an argv[0] containing an ANSI terminal escape sequence, leading to a denial of service (terminal locked up) when netstat is used by"
      },
      {
        "id": "CVE-2025-46394",
        "package": "busybox",
        "severity": "LOW",
        "installed_version": "1.36.1-r20",
        "fixed_version": "1.36.1-r21",
        "description": "In tar in BusyBox through 1.37.0, a TAR archive can have filenames hidden from a listing through the use of terminal escape sequences."
      }
    ]
  }
}
```

Each finding's `severity` is `CRITICAL`, `HIGH`, `MEDIUM`, `LOW` or `UNKNOWN`. For Trivy findings `package` is the package name; for Semgrep findings it is the file location as `path:line`. `fixed_version` is `null` when no fix is available. Descriptions are cut to 220 characters, as in the first finding above.

**Example Request (private registry image):**

```bash
curl -X POST "https://prod.api.market/api/v1/codered/vulnreport/scan?wait_seconds=25" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target":"registry.example.com/myorg/myapp:latest","scan_type":"image","registry_username":"YOUR_REGISTRY_USERNAME","registry_password":"YOUR_REGISTRY_TOKEN","format":"json"}'
```

**Example Request (private git repository, PDF report):**

```bash
curl -X POST "https://prod.api.market/api/v1/codered/vulnreport/scan?wait_seconds=25" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target":"https://github.com/username/private-demo-repo.git","scan_type":"repo","branch":"main","git_username":"oauth2","git_token":"YOUR_GITHUB_TOKEN","format":"pdf","report_title":"Private Repo Audit"}' \
  -o report.pdf
```

If this PDF scan is still running when the wait ends, the body is the JSON `202` response instead of a PDF; poll the job and fetch the report with Download a PDF report.

#### 2. Scan an uploaded codebase

Scans an archive of your own codebase with Trivy and Semgrep, with no public repository needed. Send the archive as multipart form data. The wait, polling, PDF and caching behaviour is the same as Scan a container image or git repository; uploads are cached by the archive's SHA-256 content hash, so uploading the same archive again returns the cached result.

**Method:** `POST`

**Endpoint:** `/scan/upload`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `wait_seconds` | query | Seconds to hold the request open for the finished result before returning `202` with a job ID. Use `0` to get a job ID straight away. | number | No | `20` | `55` |
| `file` | form | Archive of the codebase to scan. Allowed extensions: `.zip`, `.tar`, `.tar.gz`, `.tgz`, `.tar.bz2`, `.tbz2`. | file | Yes | - | 300MB |
| `format` | form | `json` for findings in the response, `pdf` for a rendered report. | string | No | `json` | - |
| `report_title` | form | Title printed on the PDF report. Only used when `format` is `pdf`. | string | No | - | - |

**Example Request:**

```bash
curl -X POST "https://prod.api.market/api/v1/codered/vulnreport/scan/upload?wait_seconds=25" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -F "file=@./myproject.zip" \
  -F "format=json"
```

The response has the same shape as Scan a container image or git repository: `200` with the result (or the PDF file for `format=pdf`) when the scan finishes in time, or `202` with a `job_id` and `status_url` when it is still running. An upload over 300MB returns `413`, and an archive with an unsupported extension returns `400`.

#### 3. Get a scan job

Returns the current status of a scan job, and its result once finished. `status` is one of `queued`, `started`, `deferred`, `finished`, `failed` or `stopped`. While the job waits, the response may include `position_in_queue`. A finished JSON job carries `result`; a finished PDF job carries a `download_url` (for example `/scan/jobs/{job_id}/download`) that you call through the same base URL; a failed job carries a short `error` message. Polls that return a still-running status are free; the poll that returns the finished result is billed as 1 call.

**Method:** `GET`

**Endpoint:** `/scan/jobs/{job_id}`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `job_id` | path | The `job_id` returned by a scan call. | string | Yes | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/codered/vulnreport/scan/jobs/c0febc3d-f7aa-4040-b4f7-84464118e1d6" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK, abridged to 2 of 10 findings):**

```json
{
  "job_id": "c0febc3d-f7aa-4040-b4f7-84464118e1d6",
  "status": "finished",
  "result": {
    "target": "alpine:3.19",
    "scan_type": "image",
    "scan_date": "2026-09-16T16:35:03.630551Z",
    "risk_score": 23,
    "summary": {
      "critical": 0,
      "high": 2,
      "medium": 5,
      "low": 3
    },
    "total_findings": 10,
    "findings": [
      {
        "id": "CVE-2024-58251",
        "package": "busybox",
        "severity": "MEDIUM",
        "installed_version": "1.36.1-r20",
        "fixed_version": "1.36.1-r21",
        "description": "In netstat in BusyBox through 1.37.0, local users can launch of network application with an argv[0] containing an ANSI terminal escape sequence, leading to a denial of service (terminal locked up) when netstat is used by"
      },
      {
        "id": "CVE-2025-46394",
        "package": "busybox",
        "severity": "LOW",
        "installed_version": "1.36.1-r20",
        "fixed_version": "1.36.1-r21",
        "description": "In tar in BusyBox through 1.37.0, a TAR archive can have filenames hidden from a listing through the use of terminal escape sequences."
      }
    ]
  }
}
```

A job ID that has expired or never existed returns `404`.

#### 4. Download a PDF report

Returns the finished PDF report for a job that was run with `format=pdf`, as a binary `application/pdf` file. Save it with `-o`. Calling it for a JSON job returns `400` with `{"detail":"this job was not run with format='pdf'"}`; calling it before the job has finished returns `409`; and a report that has already been cleaned up returns `410`.

**Method:** `GET`

**Endpoint:** `/scan/jobs/{job_id}/download`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `job_id` | path | The `job_id` of a scan run with `format=pdf`. | string | Yes | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/codered/vulnreport/scan/jobs/YOUR_JOB_ID/download" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -o report.pdf
```

#### 5. Health check

Returns the service status. Use it to check that the scanner is reachable before sending scans.

**Method:** `GET`

**Endpoint:** `/health`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| - | - | No parameters. | - | - | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/codered/vulnreport/health" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK):**

```json
{
  "status": "ok"
}
```

### Typical flow

1. `POST /scan` (image or repository) or `POST /scan/upload` (your own archive) with `wait_seconds` set, for example `25`.
2. If the response is `200`, you have the result (or the PDF file). You are done.
3. If the response is `202`, save the `job_id` and poll `GET /scan/jobs/{job_id}` every 10 to 15 seconds until `status` is `finished` or `failed`. Polls that return a running status are free.
4. For a PDF job, call `GET /scan/jobs/{job_id}/download` and save the file.

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The scan finished (or was served from cache) and the result, PDF file, job status or health status is in the response. |
| 202 | Accepted | The scan is still running after `wait_seconds`. Poll `GET /scan/jobs/{job_id}` with the returned `job_id`. |
| 400 | Bad Request | Invalid `scan_type` or `format`, a missing or unsupported archive extension on upload, or a PDF download requested for a job that was not run with `format=pdf`. The `detail` field explains the reason. |
| 401 | Unauthorized | The `x-api-market-key` value is invalid or expired. |
| 403 | Forbidden | Your subscription does not include this endpoint. |
| 404 | Not Found | No scan job exists for that `job_id`, because it expired or never existed. |
| 409 | Conflict | The PDF download was requested before the job finished. Poll the job until `status` is `finished`. |
| 410 | Gone | The PDF report for this job is no longer available. Run the scan again. |
| 413 | Payload Too Large | The uploaded archive is over the 300MB limit. |
| 429 | Too Many Requests | You went over your plan's requests-per-second limit or quota, or you already have too many scans in flight. |
| 500 | Internal Server Error | Something failed while processing the request. Retry after a short delay. |

## Rate Limits

The Free, Pro and Bulk plans each allow 2 requests per second. The API can also return `429` when you already have too many scans running at once, so wait for running jobs to finish before starting more. Poll job status every 10 to 15 seconds rather than in a tight loop; polls that return a running status are free but still count toward the per-second limit. Requests above the limit return `429 Too Many Requests`; back off before retrying and honour any `Retry-After` header.

## FAQ

**How am I charged?**

A call that returns a finished scan result counts as 1 call against your plan. A job poll that returns a still-running status is free, so waiting on a long scan does not use up your quota.

**Do I get the result in one call or do I need to poll?**

Both are possible. Pass `wait_seconds` (up to 55). If the scan finishes in that time you get the result with `200` in the same call. If it is still running you get `202` with a `job_id`, and you poll `GET /scan/jobs/{job_id}` until it finishes. Cached targets always return `200` straight away.

**How do I scan my own code that is not in a public repository?**

Either upload an archive of it to `POST /scan/upload` (.zip, .tar, .tar.gz, .tgz, .tar.bz2 or .tbz2, up to 300MB), or scan the private repository with `POST /scan` using `scan_type: "repo"` and a read token in `git_token`.

**Can I scan private registry images and private repositories?**

Yes. For images, pass `registry_username` and `registry_password` (a password, personal access token or robot token). For repositories, pass `git_token`, plus `git_username` where your git host needs one, such as GitLab, or `oauth2` with a GitHub token. Requests that include credentials skip the cache, so credentials are never stored as a cache key.

**What is the difference between image, repository and upload scans?**

Image scans run Trivy against the container image and report CVEs in OS packages and dependencies. Repository and upload scans run Trivy and Semgrep, so they also report code-level issues such as hardcoded secrets and injection risks. Semgrep findings show the file location as `path:line` in the `package` field.

**Why did a repeat scan come back instantly?**

Results are cached by target, and uploads by the archive's content hash. Scanning an unchanged target returns the cached result without running the scanners again.

**How do I get a PDF report?**

Set `format` to `pdf`, and optionally `report_title`. If the scan finishes within `wait_seconds`, the response is the PDF file. If not, poll the job; once it is finished, fetch the file from `GET /scan/jobs/{job_id}/download`.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Vulnerability scanner API for container images, git repos and code archives. Returns CVE findings by severity, a 0 to 100 risk score and optional PDF reports.

Vulnerability Scanner API for Images, Repos and Code