Automating API Security Linting in CI/CD

APIs are the main attack surface of modern applications, and many of their worst flaws are visible in code or in the API specification long before they reach production. API security linting means automatically analyzing source code, configuration and OpenAPI definitions for known anti-patterns, in the same way a style linter checks formatting. This article covers what to check, where to run it, and how to keep it useful.

What linting catches, and what it does not

Linting is static: it reads artifacts without running the service. It is good at problems with a recognizable pattern, and weak at problems that depend on business context.

Static linting complements, but does not replace, dynamic testing and manual review.

Checks worth enabling first

1. Secrets in code. API keys, database URLs with passwords, private keys and cloud credentials. This single category prevents the most expensive incidents. See Secrets Management.

2. Cryptography. Flag MD5 and SHA-1 for security purposes, ECB mode, hardcoded IVs, Math.random() for tokens, and RSA keys under 2048 bits. Also flag quantum-vulnerable algorithms so that they appear in your cryptographic inventory.

3. API specification rules. Lint the OpenAPI file: every operation declares a security scheme, no endpoint returns sensitive fields without authentication, request bodies have size and type limits, and error responses do not leak stack traces.

4. Injection sinks. String-built SQL, eval, shell execution with user input, unsafe deserialization.

5. Dangerous configuration. Permissive CORS, disabled TLS verification (rejectUnauthorized: false), debug mode in production configs, wildcard IAM permissions in infrastructure code.

6. Dependencies. Known vulnerabilities in packages, plus unpinned or unexpected sources.

Where to run it

Editor and pre-commit. Fast checks (secrets, obvious crypto misuse) run locally in seconds. This is where leaked secrets are cheapest to stop, because the value never enters version history.

Pull-request pipeline. Run the full suite on every pull request and report findings as annotations. Upload results in SARIF format so they appear in the code-scanning view. See Running Security Scanners as a GitHub Action.

Scheduled scans. Run the full suite nightly on the default branch to catch newly published vulnerabilities in old code.

Making the gate trustworthy

A linter that blocks merges with false alarms teaches developers to ignore it. Tune deliberately:

• Start in report-only mode for two weeks, review the findings, and fix the rules before enforcing.
• Block only on high-confidence, high-severity findings (verified secrets, critical vulnerabilities). Report the rest as warnings.
• Allow suppressions with a reason and an expiry, in code review, rather than silent ignore lists.
• Track the false-positive rate per rule, and disable or fix rules above a threshold.
• Show the fix. Findings that include a remediation suggestion are resolved much faster than ones that only name the problem.

A minimal pull-request example

name: security-lint
on: [pull_request]
permissions:
  contents: read
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Scan for secrets
        run: |
          docker run --rm -v "$PWD:/repo" zricethezav/gitleaks:latest detect --source /repo --no-banner
      - name: Lint OpenAPI
        run: npx @stoplight/spectral-cli lint openapi.yaml

Pin third-party actions and images to specific versions or digests in real pipelines; the reasons are explained in the GitHub Actions article linked above.

Measuring success

Useful indicators are the number of secrets caught before merge, time from finding to fix, and the fraction of pull requests scanned. A falling count of production incidents caused by known-pattern flaws is the real outcome, but it lags. Start small, enforce on a few high-value rules, and expand as trust grows.