Name: Shipshape API: Dockerfile and Kubernetes Linter, PSS Checks
Brand: hybrid-forge-lab
SKU: api-hybrid-forge-lab-shipshape
Availability: InStock
Author: API Market

# Shipshape Dockerfile and Kubernetes Lint API

## Overview

The Shipshape API lints Dockerfiles and Kubernetes manifests and returns every finding with its line, a concrete fix and the standard behind it. `POST /v1/dockerfile` and `POST /v1/kubernetes` lint one file type, `POST /v1/lint` detects the type for you, `GET /v1/rules` lists all 59 rules (26 for Dockerfiles, 33 for Kubernetes) and `GET /v1/health` tells you the service is up. Kubernetes checks are mapped to the Pod Security Standards baseline and restricted profiles.

It is built for platform engineers, DevOps teams, security reviewers and CI pipeline authors who want one HTTP call instead of installing and updating several linters. Each answer carries a 0 to 100 `score`, an A to F `grade`, a `passed` flag based on your `fail_on` threshold, a summary by severity and a `findings` list where each item names its rule id, severity, line, object, fix and reference (Pod Security Standards, NSA/CISA hardening, CIS Docker Benchmark or hadolint).

## Features

*   **Five endpoints**: Dockerfile lint, Kubernetes lint, auto-detect lint, the rule list and a health check.
*   **59 rules**: 26 Dockerfile rules and 33 Kubernetes rules, 20 of them mapped to Pod Security Standards.
*   **Actionable findings**: every finding has its line, the object or container it applies to, a fix and a reference link.
*   **Score and grade**: a 0 to 100 score, an A to F grade and a pass/fail your CI can act on.
*   **Thresholds and ignores**: `fail_on` sets the severity that fails the check, and `ignore` skips rule ids.
*   **Multi-stage and multi-doc**: multi-stage Dockerfiles and multi-document YAML, JSON or a `kind: List` are supported.
*   **Rate limit**: up to 10 requests per second on every plan.

## Use Cases

*   **CI gates**: fail a build when a Dockerfile or manifest has high-severity findings.
*   **Pull request review**: post the findings and their fixes as review comments.
*   **Security audits**: check existing manifests against Pod Security Standards.
*   **Internal platforms**: lint what users submit to a deploy portal before it reaches the cluster.
*   **Teaching**: show new engineers why a line is risky and how to fix it.

## API Documentation

### Base URL

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

```
https://prod.api.market/api/v1/hybrid-forge-lab/shipshape
```

### 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. Health check

Returns `ok`, the service version and its uptime.

**Method:** `GET`

**Endpoint:** `/v1/health`

**Parameters:**

This endpoint takes no parameters.

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/hybrid-forge-lab/shipshape/v1/health' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "ok": true,
  "version": "0.2.1",
  "uptime_s": 0
}
```

#### 2. Lint a Dockerfile

Lints a Dockerfile and returns the score, grade, pass/fail, a summary by severity and the findings. The example Dockerfile runs as root, pipes a remote script into a shell and bakes a secret into `ENV`.

**Method:** `POST`

**Endpoint:** `/v1/dockerfile`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `content` | body | The full Dockerfile as a string. | string | Yes | - | - |
| `ignore` | body | Rule ids to skip, for example `["DF-017"]`. | array of strings | No | - | - |
| `fail_on` | body | Lowest severity that makes `passed` false: `high`, `medium`, `low`, `info` or `never`. | string | No | `high` | - |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/hybrid-forge-lab/shipshape/v1/dockerfile' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "content": "FROM node:latest\nRUN apt-get update && apt-get install -y curl\nRUN curl -sL https://example.com/install.sh | sh\nENV API_TOKEN=supersecret123\nCOPY . /app\nCMD [\"node\",\"/app/index.js\"]\n",
  "fail_on": "high"
}'
```

**Example Response (200 OK):**

```json
{
  "type": "dockerfile",
  "passed": false,
  "fail_on": "high",
  "score": 26,
  "grade": "E",
  "summary": {
    "high": 3,
    "medium": 1,
    "low": 2,
    "info": 2,
    "total": 8
  },
  "findings": [
    {
      "id": "DF-001",
      "severity": "high",
      "category": "security",
      "title": "Final stage never sets USER, so the container runs as root",
      "detail": "No USER in the final stage (or the stages it builds on), so the process runs as root unless `node:latest` sets a non-root user itself.",
      "line": 1,
      "document": null,
      "object": "stage 0",
      "container": null,
      "fix": "Create an unprivileged user and add `USER <name or uid>` to the final stage.",
      "reference": "hadolint DL3002; CIS Docker Benchmark 4.1",
      "url": "https://docs.docker.com/build/building/best-practices/",
      "pss": null
    },
    {
      "id": "DF-008",
      "severity": "high",
      "category": "supply-chain",
      "title": "Remote script piped straight into a shell or interpreter",
      "detail": "A script fetched over the network is executed without any integrity check.",
      "line": 3,
      "document": null,
      "object": "stage 0",
      "container": null,
      "fix": "Download to a file, verify its checksum or signature, then run it.",
      "reference": "CIS Docker Benchmark 4.9",
      "url": "https://docs.docker.com/build/building/best-practices/",
      "pss": null
    }
  ],
  "truncated": false,
  "ignored": [],
  "stages": [
    {
      "index": 0,
      "name": null,
      "image": "node:latest",
      "line": 1,
      "final": true,
      "in_final_image": true
    }
  ],
  "objects": null,
  "took_ms": 1
}
```

#### 3. Lint Kubernetes manifests

Lints Kubernetes YAML or JSON (multi-document, or a `kind: List`) and returns the same shape as the Dockerfile endpoint, with each finding's document, object, container and Pod Security Standards profile.

**Method:** `POST`

**Endpoint:** `/v1/kubernetes`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `content` | body | The manifest as a YAML or JSON string. | string | Yes | - | - |
| `ignore` | body | Rule ids to skip, for example `["K8S-022"]`. | array of strings | No | - | - |
| `fail_on` | body | Lowest severity that makes `passed` false: `high`, `medium`, `low`, `info` or `never`. | string | No | `high` | - |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/hybrid-forge-lab/shipshape/v1/kubernetes' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "content": "apiVersion: v1\nkind: Pod\nmetadata:\n  name: web\nspec:\n  containers:\n  - name: web\n    image: nginx:latest\n    securityContext:\n      privileged: true\n",
  "fail_on": "high"
}'
```

**Example Response (200 OK):**

```json
{
  "type": "kubernetes",
  "passed": false,
  "fail_on": "high",
  "score": 14,
  "grade": "F",
  "summary": {
    "high": 1,
    "medium": 6,
    "low": 6,
    "info": 2,
    "total": 15
  },
  "findings": [
    {
      "id": "K8S-001",
      "severity": "high",
      "category": "security",
      "title": "Privileged container",
      "detail": "Privileged containers have every capability and full access to the node's devices.",
      "line": 10,
      "document": 1,
      "object": "Pod/web",
      "container": "web",
      "fix": "Remove `securityContext.privileged: true`; grant only the specific capabilities needed.",
      "reference": "PSS Baseline: Privileged Containers; NSA/CISA hardening",
      "url": "https://kubernetes.io/docs/concepts/security/pod-security-standards/",
      "pss": "baseline"
    },
    {
      "id": "K8S-022",
      "severity": "medium",
      "category": "reliability",
      "title": "No memory limit",
      "detail": "Without a memory limit the container can use all of the node's memory and get other pods evicted or OOM-killed.",
      "line": 7,
      "document": 1,
      "object": "Pod/web",
      "container": "web",
      "fix": "Set `resources.limits.memory`; without it one container can exhaust the node's memory.",
      "reference": "Kubernetes: resource management; NSA/CISA hardening",
      "url": "https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/",
      "pss": null
    }
  ],
  "truncated": false,
  "ignored": [],
  "stages": null,
  "objects": [
    {
      "document": 1,
      "kind": "Pod",
      "name": "web",
      "namespace": null,
      "line": 1,
      "containers": [
        "web"
      ],
      "checked": true
    }
  ],
  "took_ms": 2
}
```

#### 4. Lint with type detection

Detects whether `content` is a Dockerfile or a Kubernetes manifest and lints it. Set `type` to skip the detection.

**Method:** `POST`

**Endpoint:** `/v1/lint`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `content` | body | A Dockerfile or a Kubernetes manifest as a string. | string | Yes | - | - |
| `ignore` | body | Rule ids to skip. | array of strings | No | - | - |
| `fail_on` | body | Lowest severity that makes `passed` false: `high`, `medium`, `low`, `info` or `never`. | string | No | `high` | - |
| `type` | body | `auto`, `dockerfile` or `kubernetes`. | string | No | `auto` | - |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/hybrid-forge-lab/shipshape/v1/lint' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "content": "apiVersion: v1\nkind: Pod\nmetadata:\n  name: web\nspec:\n  containers:\n  - name: web\n    image: nginx:latest\n    securityContext:\n      privileged: true\n",
  "type": "auto",
  "fail_on": "high"
}'
```

**Example Response (200 OK):**

```json
{
  "type": "kubernetes",
  "passed": false,
  "fail_on": "high",
  "score": 14,
  "grade": "F",
  "summary": {
    "high": 1,
    "medium": 6,
    "low": 6,
    "info": 2,
    "total": 15
  },
  "findings": [
    {
      "id": "K8S-001",
      "severity": "high",
      "category": "security",
      "title": "Privileged container",
      "detail": "Privileged containers have every capability and full access to the node's devices.",
      "line": 10,
      "document": 1,
      "object": "Pod/web",
      "container": "web",
      "fix": "Remove `securityContext.privileged: true`; grant only the specific capabilities needed.",
      "reference": "PSS Baseline: Privileged Containers; NSA/CISA hardening",
      "url": "https://kubernetes.io/docs/concepts/security/pod-security-standards/",
      "pss": "baseline"
    },
    {
      "id": "K8S-022",
      "severity": "medium",
      "category": "reliability",
      "title": "No memory limit",
      "detail": "Without a memory limit the container can use all of the node's memory and get other pods evicted or OOM-killed.",
      "line": 7,
      "document": 1,
      "object": "Pod/web",
      "container": "web",
      "fix": "Set `resources.limits.memory`; without it one container can exhaust the node's memory.",
      "reference": "Kubernetes: resource management; NSA/CISA hardening",
      "url": "https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/",
      "pss": null
    }
  ],
  "truncated": false,
  "ignored": [],
  "stages": null,
  "objects": [
    {
      "document": 1,
      "kind": "Pod",
      "name": "web",
      "namespace": null,
      "line": 1,
      "containers": [
        "web"
      ],
      "checked": true
    }
  ],
  "took_ms": 3
}
```

#### 5. List rules

Returns every rule with its id, target, severity, category, title, fix and reference. Use the ids in `ignore`.

**Method:** `GET`

**Endpoint:** `/v1/rules`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `target` | query | Only rules for `dockerfile` or `kubernetes`. | string | No | - | - |

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/hybrid-forge-lab/shipshape/v1/rules' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
[
  {
    "id": "DF-001",
    "target": "dockerfile",
    "severity": "high",
    "category": "security",
    "title": "Final stage never sets USER, so the container runs as root",
    "fix": "Create an unprivileged user and add `USER <name or uid>` to the final stage.",
    "reference": "hadolint DL3002; CIS Docker Benchmark 4.1",
    "url": "https://docs.docker.com/build/building/best-practices/",
    "pss": null
  }
]
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The file was linted. A file with findings is still a 200; check `passed`, `grade` and `findings`. |
| 400 | Bad Request | The JSON body is malformed, `content` is missing, or the YAML or Dockerfile cannot be parsed. |
| 401 | Unauthorized | The `x-api-market-key` header is missing or the key is not valid. |
| 403 | Forbidden | Your key has no active subscription to this API, your plan quota is used up, or the endpoint is not part of your plan. |
| 404 | Not Found | The path is wrong. This API has `GET /v1/health`, `POST /v1/dockerfile`, `POST /v1/kubernetes`, `POST /v1/lint` and `GET /v1/rules`. |
| 429 | Too Many Requests | You sent more than 10 requests per second. Wait for the time in `Retry-After` and try again. |
| 500 | Internal Server Error | Something failed on the provider side. Retry once; if it keeps failing, contact us. |
| 503 | Service Unavailable | The service is briefly unavailable. Retry after a short pause. |

## Rate Limits

Every plan allows up to 10 requests per second. Monthly quotas are 15 calls on Free (a 7-day trial), 10,000 on Pro, 60,000 on Ultra and 300,000 on Mega, and each request counts as one call whatever it returns. Going over 10 requests per second returns `429 Too Many Requests`. Throttle your client, back off when you get a 429 and honour the `Retry-After` header before retrying.

## FAQ

*   **How is `passed` decided?**

    `passed` is false when there is at least one finding at or above the `fail_on` severity. The default is `high`; set `never` to always pass and only read the score.

*   **How do I silence a rule?**

    Add its id (for example `DF-017`) to `ignore`. `GET /v1/rules` lists every id.

*   **Can I send several manifests at once?**

    Yes. Send multi-document YAML separated by `---`, a JSON array, or a `kind: List`. Each finding has a `document` number and an `object` name.

*   **Is my file executed or stored?**

    No. Files are parsed in memory with safe YAML loading, never executed and not stored.

*   **Which standards are the rules based on?**

    Each rule names its source in `reference`: Pod Security Standards, NSA/CISA Kubernetes hardening, the CIS Docker Benchmark or hadolint.

## 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.


Lint Dockerfiles and Kubernetes manifests over HTTP: 59 rules, Pod Security Standards mapping, line-level fixes, a score and an A to F grade.

Shipshape API: Dockerfile and Kubernetes Linter, PSS Checks

Free