security-headers-action

GitHub Action to analyze HTTP response headers using securityheaders.com API.

This composite action uses standard Bash facilities along with curl and jq.

Tested on Linux, macOS, and Windows GHA runners. See CI workflow for details.

Usage

Inputs

Input	Required	Default	Description
api-key	true		API key from https://securityheaders.com/api/
domain-or-url	true		Domain or URL to analyze HTTP response headers
follow-redirects	false	true	Follow redirect status codes
hide-results-on-homepage	false	true	Hide results on homepage
api-timeout-in-seconds	false	30	API timeout in seconds (must be +ve, -ve value means default)
max-retries-on-api-error	false	0	Maximum number of retries on API error (must be +ve; -ve value means default)
expected-grade	false		Expected grade [A+ to F; or maybe R if follow-redirects: false] (invalid value means default)

• To store the API key, prefer using GitHub Actions secrets.

• The grade lower than expected-grade will result in failure.

Outputs

Output	Description
results-as-json	Complete results in JSON format
summary-as-json	Extracted summary in JSON format
grade	Extracted grade [A+ to F; or maybe R if follow-redirects: false]

Examples

Analyze and print output in the next step

- name: Analyze HTTP response headers
  uses: iamazeem/security-headers-action@v1
  id: analyze
  with:
    api-key: ${{ secrets.API_KEY }}
    domain-or-url: securityheaders.com

- name: Print output
  env:
    RESULTS_AS_JSON: ${{ steps.analyze.outputs.results-as-json }}
    SUMMARY_AS_JSON: ${{ steps.analyze.outputs.summary-as-json }}
    GRADE: ${{ steps.analyze.outputs.grade }}
  run: |
    jq '.' <<<"$RESULTS_AS_JSON"
    jq '.' <<<"$SUMMARY_AS_JSON"
    echo "GRADE: [$GRADE]"

Analyze and fail on an unexpected grade

- name: Analyze HTTP response headers
  uses: iamazeem/security-headers-action@v1
  id: analyze
  with:
    api-key: ${{ secrets.API_KEY }}
    domain-or-url: securityheaders.com
    expected-grade: A+                    # should fail on lower grade

Analyze and retry on failure

- name: Analyze HTTP response headers
  uses: iamazeem/security-headers-action@v1
  id: analyze
  with:
    api-key: ${{ secrets.API_KEY }}
    domain-or-url: securityheaders.com
    max-retries-on-api-error: 2           # will retry on failure

Contribute

You may create issues to report bugs or propose new features and enhancements.

PRs are always welcome. Please follow this workflow for submitting PRs:

• Fork the repo.
• Check out the latest main branch.
• Create a feature or bugfix branch from main.
• Commit and push changes to your forked repo.
• Make sure to add tests. See CI.
• Lint and fix Bash issues with shellcheck online or with vscode-shellcheck extension.
• Lint and fix README Markdown issues with vscode-markdownlint extension.
• Submit the PR.

License

MIT