Skip to content

Commit 040c120

Browse files
committed
fix(protect): make the rule counts add up and say where the rules came from
- the runtime check's split includes outgoing rules, so it adds up to the two totals - rules are 'from Patchstack' only when fetched; otherwise 'from its bundled rules file' - the guard's own rules count is 'local', which also covers rules the host configures - setup and the summary say 'protection rules from Patchstack' instead of 'available' - setup does not mention the guard for an app with no server - one rule is 'rule', not 'rules'
1 parent 2ffb932 commit 040c120

9 files changed

Lines changed: 40 additions & 22 deletions

File tree

‎AGENT-INSTALL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -164,7 +164,7 @@ https://api.patchstack.com/monitor/claim?site=…
164164
When you've connected, say **done**.
165165

166166
#### What Patchstack found
167-
🔴 High **1** · 🟠 Medium **3** · 🔵 Low **1** · 12 packages outdated · 12 protection rules available
167+
🔴 High **1** · 🟠 Medium **3** · 🔵 Low **1** · 12 packages outdated · 12 protection rules from Patchstack
168168

169169
**Refresh your app's preview** to see the Patchstack widget.
170170

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -147,7 +147,7 @@ That's it. `setup` adds `@patchstack/connect` to the project when it is missing
147147

148148
If the server is already running, let the framework reload and check what it actually loaded: `patchstack-connect protect --check --runtime-url https://your-preview.example/api/contact` (loopback HTTP also works). You can supply the same `--runtime-url` to `setup`. This sends one signed, read-only OPTIONS challenge to that explicit URL, without sending the API key or following redirects. The response proves that a guard on that route loaded the current map, and reports its rule-readiness state and active rule counts. It does not prove other routes are covered or that an exploit is blocked. Both CLI and server need the site's server-side credential; `{ activationCheck: false }` disables the responder. If the guard cannot answer or carries an old map, restart/rebuild/deploy and check again. Setup never starts, builds or deploys your app.
149149

150-
Scaffolded guards refresh rules on a timer and on requests: once the rules are older than the refresh interval a request waits for the fetch, and every 30 seconds before that a serving guard re-checks in the background without holding any request, so a host that freezes between requests, or runs many copies of the app, picks up a rule change. Request-triggered refresh waits at most 2500ms by default, shares concurrent work, backs off after failures, and keeps last-known-good policy when offline. It never scans source or reports a manifest in the request path. A request with the header `x-patchstack-sync` runs that refresh straight away, at most once per 15 seconds; Patchstack sends one to the live site after its rules change. Hand-wired guards can configure `requestRefreshMs` (defaults to `refreshMs`, or zero when polling is disabled) and `requestRefreshTimeoutMs` (50–3000ms), or set the former to zero to opt out. `protection.synchronization` exposes the loaded identity, last successful lookup time, source health, readiness, rule counts (split into rules from Patchstack and rules built into the guard) and scoped-rule blocking counts without a network call. Rule refresh does not change the loaded map identity.
150+
Scaffolded guards refresh rules on a timer and on requests: once the rules are older than the refresh interval a request waits for the fetch, and every 30 seconds before that a serving guard re-checks in the background without holding any request, so a host that freezes between requests, or runs many copies of the app, picks up a rule change. Request-triggered refresh waits at most 2500ms by default, shares concurrent work, backs off after failures, and keeps last-known-good policy when offline. It never scans source or reports a manifest in the request path. A request with the header `x-patchstack-sync` runs that refresh straight away, at most once per 15 seconds; Patchstack sends one to the live site after its rules change. Hand-wired guards can configure `requestRefreshMs` (defaults to `refreshMs`, or zero when polling is disabled) and `requestRefreshTimeoutMs` (50–3000ms), or set the former to zero to opt out. `protection.synchronization` exposes the loaded identity, last successful lookup time, source health, readiness, rule counts (`delivered` from Patchstack or the bundled rules file, `local` from the guard's own response and outgoing rules; `request`, `response` and `egress` count both) and scoped-rule blocking counts without a network call. Rule refresh does not change the loaded map identity.
151151

152152
The authenticated rules response may include `X-Patchstack-Map-Rules: pending | ready` alongside `X-Patchstack-Build-Match` and `X-Patchstack-Build-ID`, including on a `304`. Readiness applies only when the response confirms the exact map identity requested. An absent or unrecognized readiness value means **unknown**, not ready. The ETag identifies the delivered policy, not map-generation completion. Broad and hardening rules remain usable while map-specific rules are pending.
153153

‎src/activation-check.ts‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -36,12 +36,14 @@ export async function checkActivation(url: string, config: Config, cwd: string,
3636
if (!status || status.siteUuid !== config.siteUuid) return {ok:false,message:'The selected URL did not prove activation for this site. Check the server credential, guard integration and deployed package version.'};
3737
if (!expectedBuildId || status.buildId !== expectedBuildId) return {ok:false,message:'The guard answered, but its loaded map is absent or different. Let the framework reload, or restart/rebuild/deploy, then check again.'};
3838
const readiness = ['ready','pending'].includes(String(status.mapRules)) ? status.mapRules : 'unknown';
39-
const rules = status.rules as {request?:number;response?:number;delivered?:number;builtIn?:number;scopedBlocking?:number} | undefined;
39+
const rules = status.rules as {request?:number;response?:number;egress?:number;delivered?:number;local?:number;scopedBlocking?:number} | undefined;
40+
const source = status.source as {ok?:boolean;origin?:string} | undefined;
4041
const split = `${Number(rules?.request ?? 0)} request / ${Number(rules?.response ?? 0)} response`;
41-
const counts = typeof rules?.delivered === 'number' && typeof rules.builtIn === 'number'
42-
? `${rules.delivered} rules from Patchstack + ${rules.builtIn} built into the guard (${split})`
42+
const plural = (count: number) => `${count} ${count === 1 ? 'rule' : 'rules'}`;
43+
const fetchedFromPatchstack = source?.origin === 'api' || source?.origin === 'cache';
44+
const counts = typeof rules?.delivered === 'number' && typeof rules.local === 'number'
45+
? `${plural(rules.delivered)} ${fetchedFromPatchstack ? 'from Patchstack' : 'from its bundled rules file'} + ${rules.local} of the guard's own (${split} / ${Number(rules.egress ?? 0)} outgoing)`
4346
: `${split} rules`;
44-
const source = status.source as {ok?:boolean} | undefined;
4547
const age = typeof status.lastCheckedAt === 'number' ? ` (${Math.max(0,Math.floor((Date.now()-status.lastCheckedAt)/1000))}s since last success)` : '';
4648
return {
4749
ok:true,

‎src/cli.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1674,7 +1674,7 @@ async function runSetup(args: ParsedArgs): Promise<number> {
16741674
if (synced.rules.ok) {
16751675
// Rules are enforced by protection in a server; an app without one has nothing to apply them.
16761676
if (!noServer) report.rules = synced.rules.count;
1677-
report.done.push(`Live rule lookup succeeded (${synced.rules.count} rules from Patchstack, on top of the guard's built-in rules; not proof of runtime enforcement)`);
1677+
report.done.push(`Live rule lookup succeeded (${synced.rules.count} ${synced.rules.count === 1 ? 'rule' : 'rules'} from Patchstack${noServer ? '' : ", on top of the guard's own"}; not proof of runtime enforcement)`);
16781678
if (!noServer) {
16791679
if (synced.rules.mapRules === 'ready') {
16801680
report.done.push(`Rules for this map are ready${synced.rules.count === 0 ? ' (no applicable rules)' : ''}`);

‎src/protect/protect.d.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ export interface SynchronizationStatus {
2121
source: {ok: boolean; origin: "api" | "cache" | "bundled" | "empty"; reason?: string};
2222
mode: "block" | "dry-run";
2323
devSync: boolean;
24-
rules: {request: number; response: number; egress: number; delivered: number; builtIn: number; scoped: number; scopedBlocking: number};
24+
rules: {request: number; response: number; egress: number; delivered: number; local: number; scoped: number; scopedBlocking: number};
2525
}
2626

2727
export interface Protection {

‎src/protect/runtime.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1766,7 +1766,7 @@ export async function createProtection(options = {}) {
17661766
mode,
17671767
devSync: typeof process !== 'undefined' && process.env.PATCHSTACK_DEV_SYNC === '1',
17681768
rules: {request:requestRules.length, response:responseRules.length, egress:egressRules.length,
1769-
delivered: deliveredRuleCount, builtIn: configuredResponseRules.length + configuredEgressRules.length,
1769+
delivered: deliveredRuleCount, local: configuredResponseRules.length + configuredEgressRules.length,
17701770
scoped: [...requestRules, ...responseRules, ...egressRules].filter(rule => 'build_scope' in rule).length,
17711771
scopedBlocking: [...requestRules, ...responseRules, ...egressRules].filter(rule => 'build_scope' in rule && ruleMode(rule) === 'block').length},
17721772
});

‎src/report.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -159,7 +159,7 @@ function renderConcise(
159159
if (findings.length > 0) lines.push(...findings);
160160
if ((report.rules ?? 0) > 0) {
161161
const rules = report.rules!;
162-
lines.push(` ${paint(ANSI.green, `${rules} protection ${rules === 1 ? 'rule' : 'rules'} available`)}`);
162+
lines.push(` ${paint(ANSI.green, `${rules} protection ${rules === 1 ? 'rule' : 'rules'} from Patchstack`)}`);
163163
}
164164
if (findings.length > 0 || (report.rules ?? 0) > 0) lines.push('');
165165

@@ -318,7 +318,7 @@ export function renderSummary(report: StatusReport, progress: Progress, context:
318318
const canProtect = protectionPossible(report);
319319
context = { ...context, noServer: !canProtect };
320320

321-
const rules = canProtect && (report.rules ?? 0) > 0 ? `${report.rules} protection ${report.rules === 1 ? 'rule' : 'rules'} available` : null;
321+
const rules = canProtect && (report.rules ?? 0) > 0 ? `${report.rules} protection ${report.rules === 1 ? 'rule' : 'rules'} from Patchstack` : null;
322322
let headline: string;
323323
if (counted && findings.vulnerable > 0) {
324324
const vulnerabilities = findings.severity.high + findings.severity.medium + findings.severity.low + findings.severity.unknown;

‎tests/protect/activation.test.ts‎

Lines changed: 24 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ import { afterEach, expect, it, vi } from 'vitest';
22
import { ACTIVATION_HEADER, activationChallenge, activationResponse, verifyActivationResponse } from '../../src/protect/activation.js';
33
import { createProtection } from '../../src/protect/runtime.js';
44
import { checkActivation } from '../../src/activation-check.js';
5+
import { DEFAULT_EGRESS_RULES, DEFAULT_RESPONSE_RULES } from '../../src/protect/defaults.js';
56
import type { Config } from '../../src/types.js';
67

78
const secret='synthetic-activation-secret-1234';
@@ -75,24 +76,39 @@ it.each(['ready', 'pending', 'unknown'])('keeps %s readiness and enforcement lim
7576
expect(result.summary).toContain('This does not prove blocking or protection on other URLs.');
7677
});
7778

78-
it('splits the rule count into rules from Patchstack and rules built into the guard', async () => {
79+
it('counts rules from Patchstack apart from the guard\'s own, and the two add up to the phase split', async () => {
7980
const match = [{ parameter: 'get.q', match: { type: 'contains', value: 'attack' } }];
8081
const delivered = [{ id: 'synthetic-a', rule_v2: match }, { id: 'synthetic-b', phase: 'response', rule_v2: match }];
8182
const p = await createProtection({ pulseAuth: secret, buildId: build, rules: { firewall: delivered }, cache: false, reportDetections: false });
8283
try {
8384
const { rules } = p.synchronization;
8485
expect(rules.delivered).toBe(2);
85-
expect(rules.builtIn).toBeGreaterThan(0);
86-
expect(rules.request + rules.response + rules.egress).toBe(rules.delivered + rules.builtIn);
86+
expect(rules.local).toBe(DEFAULT_RESPONSE_RULES.length + DEFAULT_EGRESS_RULES.length);
87+
expect(rules.request + rules.response + rules.egress).toBe(rules.delivered + rules.local);
8788
} finally { await p.stop(); }
89+
});
8890

91+
async function checkedWith(status: Record<string, unknown>): Promise<string> {
8992
vi.stubGlobal('fetch', async (target: string, init: RequestInit) => activationResponse(new Request(target, init), secret, () => ({
90-
siteUuid: site, buildId: build, mapRules: 'ready', source: { ok: true },
91-
rules: { request: 6, response: 20, egress: 1, delivered: 17, builtIn: 10, scopedBlocking: 0 },
93+
siteUuid: site, buildId: build, mapRules: 'ready', ...status,
9294
})));
93-
const result = await checkActivation(url, config, '.', build);
94-
expect(result.message).toContain('17 rules from Patchstack + 10 built into the guard (6 request / 20 response)');
95-
expect(result.message).toContain("0 rules for this app's own routes in blocking mode");
95+
return (await checkActivation(url, config, '.', build)).message;
96+
}
97+
98+
it('names where the rules came from, with a split that adds up', async () => {
99+
const counts = { request: 6, response: 20, egress: 2, delivered: 17, local: 11, scopedBlocking: 0 };
100+
expect(await checkedWith({ source: { ok: true, origin: 'api' }, rules: counts }))
101+
.toContain("17 rules from Patchstack + 11 of the guard's own (6 request / 20 response / 2 outgoing)");
102+
expect(await checkedWith({ source: { ok: false, origin: 'bundled' }, rules: counts }))
103+
.toContain("17 rules from its bundled rules file + 11 of the guard's own");
104+
expect(await checkedWith({ source: { ok: true, origin: 'api' }, rules: { ...counts, delivered: 1 } }))
105+
.toContain('1 rule from Patchstack');
106+
});
107+
108+
it('keeps the phase split alone for a guard that does not report where its rules came from', async () => {
109+
const message = await checkedWith({ source: { ok: true, origin: 'api' }, rules: { request: 6, response: 20, scopedBlocking: 0 } });
110+
expect(message).toContain('; 6 request / 20 response rules;');
111+
expect(message).not.toContain('from Patchstack');
96112
});
97113

98114
it('bounds a transport that ignores abort', async()=>{

‎tests/report.test.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,7 @@ describe('renderStatus concise', () => {
8989
' Low ███████░░░░░░░░░░░░░ 1',
9090
'',
9191
' 12 packages are outdated',
92-
' 12 protection rules available',
92+
' 12 protection rules from Patchstack',
9393
'',
9494
'More npx @patchstack/connect vulns vulnerability details',
9595
]);
@@ -199,7 +199,7 @@ describe('renderSummary', () => {
199199
`When you've connected, say **done**.`,
200200
'',
201201
'#### What Patchstack found',
202-
'🔴 High **1** · 🟠 Medium **3** · 🔵 Low **1** · 12 packages outdated · 12 protection rules available',
202+
'🔴 High **1** · 🟠 Medium **3** · 🔵 Low **1** · 12 packages outdated · 12 protection rules from Patchstack',
203203
'',
204204
"**Refresh your app's preview** to see the Patchstack widget.",
205205
]);
@@ -285,7 +285,7 @@ describe('renderSummary', () => {
285285
it('never states a count the run did not get', () => {
286286
const lines = renderSummary(report({ findings: null, rules: 12 }), notConnected, context, { widgetOnPage: false, dashboardUrl: null });
287287
expect(lines[5]).toBe('### 🛡️ Checked 89 packages, now watching them');
288-
expect(lines[7]).toBe('12 protection rules available.');
288+
expect(lines[7]).toBe('12 protection rules from Patchstack.');
289289
});
290290

291291
it('ends on the word AGENT-INSTALL.md maps to next, and the doc still maps the summary for later', () => {

0 commit comments

Comments
 (0)