Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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() }}
25 changes: 25 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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@<commit sha>
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)
Expand Down
66 changes: 66 additions & 0 deletions gate/action.yml
Original file line number Diff line number Diff line change
@@ -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
44 changes: 44 additions & 0 deletions gate/check.ts
Original file line number Diff line number Diff line change
@@ -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 <policy.json> [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 <policy.json> [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<Response> {
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);
31 changes: 31 additions & 0 deletions gate/examples/juice-shop.policy.json
Original file line number Diff line number Diff line change
@@ -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"
}
]
}
75 changes: 75 additions & 0 deletions gate/policy.ts
Original file line number Diff line number Diff line change
@@ -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<Policy>;
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');
}
5 changes: 5 additions & 0 deletions tests/fixtures/gate-accepts-nothing.policy.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{
"routes": ["/", "/rest/products/search?q=apple", "/api/Products/1"],
"probe": "/api/DoesNotExist",
"accepted": []
}
Loading
Loading