diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 8cb0af0..50e9188 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -75,3 +75,41 @@ jobs: name: dependency-scan-reports path: reports/ retention-days: 14 + + # Uses the gate the way another repo would: app started in this job, then the composite action. + gate-selftest: + name: Security gate self-test (Juice Shop) + needs: quality + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + - run: docker compose up -d --wait + - name: Gate passes with the Juice Shop policy (S-1 to S-5 accepted) and ZAP rules + uses: ./gate + with: + policy: gate/examples/juice-shop.policy.json + zap-rules: zap/rules.conf + - name: Gate run that accepts nothing (expected to fail) + id: must-fail + continue-on-error: true + uses: ./gate + with: + policy: tests/fixtures/gate-accepts-nothing.policy.json + report-dir: security-gate-report/must-fail + - name: Check the gate failed + env: + OUTCOME: ${{ steps.must-fail.outcome }} + run: | + if [ "$OUTCOME" != failure ]; then + echo "::error::The gate passed with a policy that accepts nothing, so it can't fail." + exit 1 + fi + echo "The gate failed as expected: $(jq -r '.unexpected | length' security-gate-report/must-fail/gate.json) unaccepted findings." + - uses: actions/upload-artifact@v7 + if: ${{ !cancelled() }} + with: + name: security-gate-report + path: security-gate-report/ + retention-days: 14 + - run: docker compose down + if: ${{ always() }} diff --git a/README.md b/README.md index 2b7c60a..dffa1f1 100644 --- a/README.md +++ b/README.md @@ -65,6 +65,31 @@ endpoints are checked to refuse requests that carry no token. lodash version with a known CVE, and fails unless Trivy reports it. That proves the scan actually detects known issues. +## Reusable security gate + +The header and error-page checks also work as a composite action for other repos. The calling job +starts its own app on localhost, then runs the gate against it: + +```yaml +- run: npm start & # however the app starts; it must listen on localhost +- uses: VincentJerico/security-testing/gate@ + with: + policy: .github/security-gate.json + target-url: http://localhost:3000 + zap-rules: zap/rules.conf # optional: also run ZAP's passive baseline +``` + +The policy lists the routes to check, an unknown route to probe for stack traces, and the +findings the repo has accepted for now, each with a reason +([example](gate/examples/juice-shop.policy.json)). Like the pinned tests here, the gate fails on a +finding nobody accepted and on an accepted finding that no longer happens, so the policy can't go +stale. It refuses any target that isn't localhost, and it runs its checks in a `node:22` +container, so it doesn't change the calling job's Node version. + +CI runs the gate against Juice Shop twice: with [its policy](gate/examples/juice-shop.policy.json) +(S-1 to S-5 accepted, plus the ZAP rules) it must pass, and with a policy that accepts nothing it +must fail. [`gate.selftest.spec.ts`](tests/gate.selftest.spec.ts) pins the policy logic. + ## Roadmap 1. Scaffold, target guard and CI (done) diff --git a/gate/action.yml b/gate/action.yml new file mode 100644 index 0000000..454e19e --- /dev/null +++ b/gate/action.yml @@ -0,0 +1,66 @@ +name: Security gate +description: > + Security checks for a web app running on localhost in the calling job: response headers, + stack traces on error pages, and an optional ZAP passive scan. Fails on findings the caller's + policy doesn't accept and on accepted findings that no longer happen. + +inputs: + policy: + description: Path to the policy JSON in the calling repo (routes, probe, accepted findings). + required: true + target-url: + description: Where the app is listening. Only localhost addresses are allowed. + default: http://localhost:3000 + zap-rules: + description: > + Path to a ZAP rules.conf in the calling repo. With it, ZAP's passive baseline runs and any + FAIL rule fails the gate. Leave empty to skip ZAP. + default: '' + report-dir: + description: Directory (in the workspace) for the gate's reports. + default: security-gate-report + +runs: + using: composite + steps: + # Node 22 in a container, so the gate doesn't change the Node version of the calling job. + - name: Header and error-page checks + shell: bash + env: + GATE_DIR: ${{ github.action_path }} + POLICY: ${{ inputs.policy }} + TARGET_URL: ${{ inputs.target-url }} + REPORT_DIR: ${{ inputs.report-dir }} + run: | + mkdir -p "$REPORT_DIR" + docker run --rm --network host \ + -v "$GATE_DIR/..:/gate:ro" -v "$GITHUB_WORKSPACE:/work" -w /work \ + -e TARGET_URL node:22.23.4-slim \ + node /gate/gate/check.ts "$POLICY" "$REPORT_DIR/gate.json" + + - name: ZAP passive baseline + if: ${{ inputs.zap-rules != '' }} + shell: bash + env: + RULES: ${{ inputs.zap-rules }} + TARGET_URL: ${{ inputs.target-url }} + REPORT_DIR: ${{ inputs.report-dir }} + run: | + mkdir -p "$REPORT_DIR/zap" + cp "$RULES" "$REPORT_DIR/zap/rules.conf" + chmod -R a+w "$REPORT_DIR/zap" + set +e + docker run --rm --network host -v "$GITHUB_WORKSPACE/$REPORT_DIR/zap:/zap/wrk:rw" \ + ghcr.io/zaproxy/zaproxy:2.17.0 zap-baseline.py -t "$TARGET_URL" \ + -c rules.conf -r report.html -J report.json + code=$? + set -e + if [ ! -s "$REPORT_DIR/zap/report.json" ]; then + echo "::error::ZAP baseline: scan error, no report.json was written (exit $code)" + exit 3 + fi + case $code in + 0 | 2) echo "ZAP baseline: no FAIL rule triggered (exit $code)" ;; + 1) echo "::error::ZAP baseline: a FAIL rule triggered, see $REPORT_DIR/zap/report.html"; exit 1 ;; + *) echo "::error::ZAP baseline: scan error (exit $code)"; exit "$code" ;; + esac diff --git a/gate/check.ts b/gate/check.ts new file mode 100644 index 0000000..0c5aaba --- /dev/null +++ b/gate/check.ts @@ -0,0 +1,44 @@ +// Run the security gate against a local app: response headers on each policy route, and a probe +// for stack traces on an unknown route. Exits 1 when the verdict isn't clean. +// +// TARGET_URL=http://localhost:3000 node gate/check.ts [report.json] +import { readFileSync, writeFileSync } from 'node:fs'; +import { checkHeaders, leaksStackTrace } from '../src/headers.ts'; +import { resolveTarget } from '../src/target.ts'; +import { STACK_TRACE, judge, parsePolicy, verdictReport, type Finding } from './policy.ts'; + +const [policyFile, reportFile] = process.argv.slice(2); +if (!policyFile) { + console.error( + 'usage: TARGET_URL=http://localhost:3000 node gate/check.ts [report.json]', + ); + process.exit(2); +} + +// Refuses anything that isn't localhost before a single request is sent. +const target = resolveTarget(process.env.TARGET_URL ?? 'http://localhost:3000'); +const policy = parsePolicy(JSON.parse(readFileSync(policyFile, 'utf8'))); + +async function get(route: string): Promise { + return fetch(new URL(route, target), { redirect: 'manual' }); +} + +const findings: Finding[] = []; +for (const route of policy.routes) { + const res = await get(route); + const headers = Object.fromEntries([...res.headers].map(([k, v]) => [k.toLowerCase(), v])); + for (const problem of checkHeaders(headers)) findings.push({ route, problem }); + console.log(`${res.status} ${route}`); +} +if (policy.probe) { + const res = await get(policy.probe); + if (leaksStackTrace(await res.text())) + findings.push({ route: policy.probe, problem: STACK_TRACE }); + console.log(`${res.status} ${policy.probe} (probe)`); +} + +const verdict = judge(findings, policy); +console.log(verdictReport(findings, verdict)); +if (reportFile) + writeFileSync(reportFile, JSON.stringify({ target, findings, ...verdict }, null, 2)); +process.exit(verdict.unexpected.length + verdict.stale.length > 0 ? 1 : 0); diff --git a/gate/examples/juice-shop.policy.json b/gate/examples/juice-shop.policy.json new file mode 100644 index 0000000..0366cae --- /dev/null +++ b/gate/examples/juice-shop.policy.json @@ -0,0 +1,31 @@ +{ + "routes": ["/", "/rest/products/search?q=apple", "/api/Products/1"], + "probe": "/api/DoesNotExist", + "accepted": [ + { + "route": "*", + "problem": "Content-Security-Policy is missing", + "reason": "S-1 in docs/FINDINGS.md; Juice Shop is deliberately vulnerable" + }, + { + "route": "*", + "problem": "Referrer-Policy is missing", + "reason": "S-2 in docs/FINDINGS.md" + }, + { + "route": "*", + "problem": "Permissions-Policy is missing", + "reason": "S-3 in docs/FINDINGS.md (Juice Shop sends the deprecated Feature-Policy)" + }, + { + "route": "*", + "problem": "Access-Control-Allow-Origin is \"*\", so any site can read responses", + "reason": "S-4 in docs/FINDINGS.md" + }, + { + "route": "/api/DoesNotExist", + "problem": "error response shows a stack trace or internal file paths", + "reason": "S-5 in docs/FINDINGS.md" + } + ] +} diff --git a/gate/policy.ts b/gate/policy.ts new file mode 100644 index 0000000..e5dfda7 --- /dev/null +++ b/gate/policy.ts @@ -0,0 +1,75 @@ +// The security gate's policy: which routes to check and which findings the caller has accepted. +// Like the pinned tests in this repo, the gate fails on a finding nobody accepted and also on an +// accepted finding that no longer happens, so the policy file can't silently go stale. + +/** Problem text the gate reports when the probe route's response shows a stack trace. */ +export const STACK_TRACE = 'error response shows a stack trace or internal file paths'; + +export interface Acceptance { + /** A route from `routes`, or "*" for every route. */ + route: string; + /** Exact problem text, as the gate prints it. */ + problem: string; + /** Why it's accepted for now. Required. */ + reason: string; +} + +export interface Policy { + routes: string[]; + /** A route that doesn't exist, requested to see whether the error page leaks a stack trace. */ + probe?: string; + accepted: Acceptance[]; +} + +export interface Finding { + route: string; + problem: string; +} + +export interface Verdict { + unexpected: Finding[]; + stale: Acceptance[]; +} + +export function parsePolicy(raw: unknown): Policy { + const p = raw as Partial; + const errors: string[] = []; + if (!Array.isArray(p.routes) || p.routes.length === 0) + errors.push('"routes" must list at least one route'); + for (const r of p.routes ?? []) + if (typeof r !== 'string' || !r.startsWith('/')) + errors.push(`route ${JSON.stringify(r)} must start with "/"`); + if (p.probe !== undefined && (typeof p.probe !== 'string' || !p.probe.startsWith('/'))) + errors.push('"probe" must start with "/"'); + if (!Array.isArray(p.accepted)) errors.push('"accepted" must be a list (it can be empty)'); + for (const a of p.accepted ?? []) { + if (!a?.route || !a?.problem || !a?.reason?.trim()) + errors.push(`accepted entry ${JSON.stringify(a)} needs route, problem and reason`); + else if (a.route !== '*' && a.route !== p.probe && !p.routes?.includes(a.route)) + errors.push(`accepted entry for ${a.route} names a route the gate doesn't check`); + } + if (errors.length) throw new Error(`Invalid security gate policy:\n- ${errors.join('\n- ')}`); + return { routes: p.routes!, probe: p.probe, accepted: p.accepted! }; +} + +const covers = (a: Acceptance, f: Finding) => + a.problem === f.problem && (a.route === '*' || a.route === f.route); + +export function judge(findings: Finding[], policy: Policy): Verdict { + return { + unexpected: findings.filter((f) => !policy.accepted.some((a) => covers(a, f))), + stale: policy.accepted.filter((a) => !findings.some((f) => covers(a, f))), + }; +} + +export function verdictReport(findings: Finding[], verdict: Verdict): string { + const lines = [ + `Security gate: ${findings.length} finding(s), ${verdict.unexpected.length} not accepted, ${verdict.stale.length} stale acceptance(s).`, + ]; + for (const f of verdict.unexpected) lines.push(` NEW ${f.route}: ${f.problem}`); + for (const a of verdict.stale) + lines.push(` STALE ${a.route}: ${a.problem} (no longer happens; remove it from the policy)`); + const accepted = findings.length - verdict.unexpected.length; + if (accepted) lines.push(` ${accepted} finding(s) matched an accepted entry.`); + return lines.join('\n'); +} diff --git a/tests/fixtures/gate-accepts-nothing.policy.json b/tests/fixtures/gate-accepts-nothing.policy.json new file mode 100644 index 0000000..443d83e --- /dev/null +++ b/tests/fixtures/gate-accepts-nothing.policy.json @@ -0,0 +1,5 @@ +{ + "routes": ["/", "/rest/products/search?q=apple", "/api/Products/1"], + "probe": "/api/DoesNotExist", + "accepted": [] +} diff --git a/tests/gate.selftest.spec.ts b/tests/gate.selftest.spec.ts new file mode 100644 index 0000000..27b1cb6 --- /dev/null +++ b/tests/gate.selftest.spec.ts @@ -0,0 +1,115 @@ +import { test, expect } from '@playwright/test'; +import { spawnSync } from 'node:child_process'; +import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join, resolve } from 'node:path'; +import { STACK_TRACE, judge, parsePolicy, type Policy } from '../gate/policy.js'; +import { TARGET } from '../src/target.js'; + +/** + * Proves the reusable security gate can fail: unaccepted findings and stale acceptances fail it, + * a bad policy is refused, and against the local Juice Shop the real policy passes while an empty + * policy fails. + */ +const POLICY: Policy = { + routes: ['/', '/api/x'], + probe: '/nope', + accepted: [ + { route: '*', problem: 'Referrer-Policy is missing', reason: 'tracked as X-1' }, + { route: '/nope', problem: STACK_TRACE, reason: 'tracked as X-2' }, + ], +}; + +test.describe('security gate policy self-test', () => { + test('accepted findings pass, on every route for "*"', () => { + const verdict = judge( + [ + { route: '/', problem: 'Referrer-Policy is missing' }, + { route: '/api/x', problem: 'Referrer-Policy is missing' }, + { route: '/nope', problem: STACK_TRACE }, + ], + POLICY, + ); + expect(verdict).toEqual({ unexpected: [], stale: [] }); + }); + + test('a finding nobody accepted fails the gate', () => { + const verdict = judge( + [ + { route: '/', problem: 'Referrer-Policy is missing' }, + { route: '/', problem: 'Content-Security-Policy is missing' }, + { route: '/nope', problem: STACK_TRACE }, + ], + POLICY, + ); + expect(verdict.unexpected).toEqual([ + { route: '/', problem: 'Content-Security-Policy is missing' }, + ]); + }); + + test('an accepted finding that no longer happens is stale and fails the gate', () => { + const verdict = judge([{ route: '/', problem: 'Referrer-Policy is missing' }], POLICY); + expect(verdict.stale).toEqual([POLICY.accepted[1]]); + }); + + test('a policy with a missing reason or an unknown route is refused', () => { + expect(() => + parsePolicy({ routes: ['/'], accepted: [{ route: '/', problem: 'x', reason: ' ' }] }), + ).toThrow('needs route, problem and reason'); + expect(() => + parsePolicy({ routes: ['/'], accepted: [{ route: '/other', problem: 'x', reason: 'y' }] }), + ).toThrow("names a route the gate doesn't check"); + expect(() => parsePolicy({ routes: [], accepted: [] })).toThrow('at least one route'); + }); +}); + +test.describe('security gate against the local Juice Shop', () => { + const runGate = (policy: unknown) => { + const dir = mkdtempSync(join(tmpdir(), 'gate-')); + const file = join(dir, 'policy.json'); + writeFileSync(file, JSON.stringify(policy)); + return spawnSync('node', [resolve('gate/check.ts'), file, join(dir, 'report.json')], { + encoding: 'utf8', + env: { ...process.env, TARGET_URL: TARGET }, + }); + }; + const juiceShop = JSON.parse(readFileSync('gate/examples/juice-shop.policy.json', 'utf8')); + + test('passes with the Juice Shop policy (S-1 to S-5 accepted)', () => { + const r = runGate(juiceShop); + expect(r.stdout).toContain('0 not accepted, 0 stale'); + expect(r.status).toBe(0); + }); + + test('fails when nothing is accepted', () => { + const r = runGate({ ...juiceShop, accepted: [] }); + expect(r.stdout).toContain(`NEW /: Content-Security-Policy is missing`); + expect(r.stdout).toContain(`NEW /api/DoesNotExist: ${STACK_TRACE}`); + expect(r.status).toBe(1); + }); + + test('fails on an acceptance for a problem Juice Shop does not have', () => { + const r = runGate({ + ...juiceShop, + accepted: [ + ...juiceShop.accepted, + { route: '*', problem: 'X-Content-Type-Options is not "nosniff"', reason: 'test' }, + ], + }); + expect(r.stdout).toContain('STALE *: X-Content-Type-Options is not "nosniff"'); + expect(r.status).toBe(1); + }); + + test('refuses a target that is not localhost', () => { + const r = spawnSync( + 'node', + [resolve('gate/check.ts'), 'gate/examples/juice-shop.policy.json'], + { + encoding: 'utf8', + env: { ...process.env, TARGET_URL: 'https://example.com' }, + }, + ); + expect(r.stderr).toContain('only tests a local app'); + expect(r.status).not.toBe(0); + }); +}); diff --git a/tsconfig.json b/tsconfig.json index 3e91dd4..2511ad2 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -5,6 +5,7 @@ "moduleResolution": "bundler", "strict": true, "noEmit": true, + "allowImportingTsExtensions": true, "esModuleInterop": true, "skipLibCheck": true, "types": ["node"]