@faable/faable 3.1.1 → 3.2.0

package/dist/commands/deploy/waf/add_rule.js

@@ -5,45 +5,59 @@ const describe_selector = (s) => {
     if (s.pattern && s.user_agent) {
         return `requests for ${s.pattern} from user-agents matching ${s.user_agent}`;
     }
+    if (s.pattern && s.query) {
+        return `requests for ${s.pattern} carrying ?${s.query}`;
+    }
     if (s.user_agent)
         return `requests from user-agents matching ${s.user_agent}`;
+    if (s.query)
+        return `requests carrying ?${s.query}`;
     return `requests for ${s.pattern}`;
 };
 /** Does this returned rule carry everything we asked for? */
 const rule_matches_request = (rule, want, action) => rule.action === action &&
     (rule.pattern ?? '') === (want.pattern ?? '') &&
-    (rule.user_agent ?? '') === (want.user_agent ?? '');
+    (rule.user_agent ?? '') === (want.user_agent ?? '') &&
+    (rule.query ?? '') === (want.query ?? '');
 /**
  * Shared handler for `block` and `sink` — the two differ only in the action
  * they store and in what the edge answers, so the flow (resolve app, write,
  * verify, explain, tell the user how to check) lives here once.
  */
 const add_rule = async (opts) => {
-    const { api, app_id, app_name, app_url, pattern, user_agent, action, description, force } = opts;
-    const want = { pattern, user_agent };
+    const { api, app_id, app_name, app_url, pattern, user_agent, query, action, description, force } = opts;
+    const want = { pattern, user_agent, query };
     const waf = await api.addAppWafRule(app_id, {
         pattern,
         user_agent,
+        query,
         action,
         description,
         force
     });
     // Read the rule back before telling the user it worked.
     //
-    // An older Faable server has no `user_agent` on this endpoint and drops it
-    // silently, storing the path half on its own — which turns "block /login for
-    // this bot" into "block /login for everyone". No server-side schema can
-    // prevent that (the old server is the old code), so the client checks that
-    // what came back is what it asked for, and undoes the write if it is not.
-    if (user_agent &&
+    // An older Faable server has no `user_agent` (or no `query`) on this endpoint
+    // and drops it silently, storing the path half on its own — which turns
+    // "block /login for this bot" into "block /login for everyone", or "block /
+    // when it carries ?rest_route" into "block /", which is the entire app. No
+    // server-side schema can prevent that (the old server is the old code), so
+    // the client checks that what came back is what it asked for, and undoes the
+    // write if it is not.
+    //
+    // The query half is the more dangerous of the two, because the api LIFTS the
+    // site-root guard for a path that is ANDed with a parameter: `^/$` is a legal
+    // pattern to send, and an old server that drops the parameter stores exactly
+    // the rule the guard exists to refuse.
+    if ((user_agent || query) &&
         !waf.rules.some(r => rule_matches_request(r, want, action))) {
         await api
-            .removeAppWafRule(app_id, { pattern, user_agent, action })
+            .removeAppWafRule(app_id, { pattern, user_agent, query, action })
             // If the rollback itself is unsupported, fall back to the path-only
             // shape the old server actually stored.
             .catch(() => api.removeAppWafRule(app_id, { pattern, action }))
             .catch(() => undefined);
-        throw new Error(`This Faable server does not support user-agent rules yet, so the rule was not created.\n` +
+        throw new Error(`This Faable server does not support ${query ? 'query-parameter' : 'user-agent'} rules yet, so the rule was not created.\n` +
             `  Update the CLI and try again, or ask support to upgrade the platform.`);
     }
     const answer = action === 'deny' ? '403' : '404';
@@ -75,7 +89,8 @@ const add_rule = async (opts) => {
 /** The exact arguments that reverse this rule. */
 const undo_args = (s) => [
     s.pattern ? `'${s.pattern}'` : '',
-    s.user_agent ? `--user-agent '${s.user_agent}'` : ''
+    s.user_agent ? `--user-agent '${s.user_agent}'` : '',
+    s.query ? `--query '${s.query}'` : ''
 ]
     .filter(Boolean)
     .join(' ');

package/dist/commands/deploy/waf/block.js

@@ -14,6 +14,11 @@ const waf_block = {
         alias: 'u',
         type: 'string',
         description: 'RE2 fragment matched against User-Agent, e.g. YisouSpider. With a path, BOTH must match.'
+    })
+        .option('query', {
+        alias: 'q',
+        type: 'string',
+        description: 'Literal query parameter name, e.g. rest_route (not a regex). With a path, BOTH must match.'
     })
         .option('app', {
         alias: 'a',
@@ -28,19 +33,24 @@ const waf_block = {
         .option('force', {
         type: 'boolean',
         default: false,
-        description: 'Accept a user-agent that also matches a known search/AI crawler or uptime monitor'
+        description: 'Accept a user-agent that also matches a known search/AI crawler or uptime monitor, or a query parameter that carries an auth flow'
     })
-        .check(({ pattern, userAgent }) => {
-        if (!pattern && !userAgent) {
-            throw new Error('Give a path pattern, --user-agent, or both.\n' +
+        .check(({ pattern, userAgent, query }) => {
+        if (userAgent && query) {
+            throw new Error('A rule can combine a path with --user-agent OR with --query, not both.');
+        }
+        if (!pattern && !userAgent && !query) {
+            throw new Error('Give a path pattern, --user-agent, --query, or a path with one of them.\n' +
                 "  e.g. faable deploy waf block '^/wp-admin'\n" +
-                '       faable deploy waf block --user-agent YisouSpider');
+                '       faable deploy waf block --user-agent YisouSpider\n' +
+                '       faable deploy waf block --query rest_route');
         }
         return true;
     })
         .example("$0 deploy waf block '^/\\.well-known/'", 'Stop scanner probes under /.well-known from waking the app')
         .example('$0 deploy waf block --user-agent YisouSpider', 'Refuse one crawler outright, on every path')
         .example("$0 deploy waf block '^/api/' --user-agent curl", 'Refuse /api/ to that user-agent only, leaving browsers untouched')
+        .example('$0 deploy waf block --query rest_route', 'Stop WordPress REST probes, whose payload rides in the query string')
         .showHelpOnFail(false),
     handler: async (args) => {
         const ctx = await requireApi();
@@ -53,6 +63,7 @@ const waf_block = {
             app_url: app.url,
             pattern: args.pattern,
             user_agent: args.userAgent,
+            query: args.query,
             action: 'deny',
             description: args.description,
             force: args.force

package/dist/commands/deploy/waf/format.js

@@ -26,10 +26,18 @@ const format_waf = (waf) => {
     for (const p of waf.platform_profiles) {
         // Say what the ruleset matches ON, not just what it answers: without it a
         // `probe` profile of user-agents reads as if it blocked paths.
-        const on = p.match === 'user_agent' ? ' by user-agent' : '';
+        const on = p.match === 'user_agent'
+            ? ' by user-agent'
+            : p.match === 'query'
+                ? ' by query parameter'
+                : '';
         out.push(`  • ${p.name} — ${p.rule_count} rule(s)${on}, ${action_label(p.action)}`);
         for (const r of p.rules ?? []) {
-            const what = p.match === 'user_agent' ? `UA ~ ${r.pattern}` : r.pattern;
+            const what = p.match === 'user_agent'
+                ? `UA ~ ${r.pattern}`
+                : p.match === 'query'
+                    ? `?${r.pattern}`
+                    : r.pattern;
             out.push(`      ${what}${r.description ? `  # ${r.description}` : ''}`);
         }
     }
@@ -48,16 +56,22 @@ const format_waf = (waf) => {
 /**
  * What a rule selects, in one line.
  *
- * The three shapes have to be visibly different here: a user-agent rule has no
- * path restriction (it applies to the whole app) and a combined one is an AND,
- * so printing either as a bare pattern would misrepresent its reach.
+ * The five shapes have to be visibly different here: a user-agent or query rule
+ * has no path restriction (it applies to the whole app) and the combined ones
+ * are ANDs, so printing any of them as a bare pattern would misrepresent its
+ * reach. The `?` prefix marks a query parameter — `rest_route` on its own would
+ * read like a path.
  */
 const rule_subject = (r) => {
     if (r.pattern && r.user_agent) {
         return `${r.pattern} + UA ~ ${r.user_agent}`;
     }
+    if (r.pattern && r.query)
+        return `${r.pattern} + ?${r.query}`;
     if (r.user_agent)
         return `UA ~ ${r.user_agent} (any path)`;
+    if (r.query)
+        return `?${r.query} (any path)`;
     return r.pattern ?? '(unknown)';
 };
 

package/dist/commands/deploy/waf/rm.js

@@ -18,6 +18,11 @@ const waf_rm = {
         alias: 'u',
         type: 'string',
         description: 'The user-agent of the rule to remove'
+    })
+        .option('query', {
+        alias: 'q',
+        type: 'string',
+        description: 'The query parameter of the rule to remove'
     })
         .option('action', {
         type: 'string',
@@ -29,9 +34,9 @@ const waf_rm = {
         type: 'string',
         description: 'App Identifier (defaults to the linked app)'
     })
-        .check(({ pattern, userAgent }) => {
-        if (!pattern && !userAgent) {
-            throw new Error('Give the path pattern, --user-agent, or both.');
+        .check(({ pattern, userAgent, query }) => {
+        if (!pattern && !userAgent && !query) {
+            throw new Error('Give the path pattern, --user-agent, --query, or a path with one of them.');
         }
         return true;
     })
@@ -45,11 +50,13 @@ const waf_rm = {
         await ctx.api.removeAppWafRule(app_id, {
             pattern: args.pattern,
             user_agent: args.userAgent,
+            query: args.query,
             action: args.action
         });
         log.info(`🗑️  Removed ${describe_selector({
             pattern: args.pattern,
-            user_agent: args.userAgent
+            user_agent: args.userAgent,
+            query: args.query
         })} from ${app.name} (${app_id}).`);
         log.info(`They reach your app again within ~20s, once the edge picks up the change.`);
     }

package/dist/commands/deploy/waf/sink.js

@@ -14,6 +14,11 @@ const waf_sink = {
         alias: 'u',
         type: 'string',
         description: 'RE2 fragment matched against User-Agent, e.g. YisouSpider. With a path, BOTH must match.'
+    })
+        .option('query', {
+        alias: 'q',
+        type: 'string',
+        description: 'Literal query parameter name, e.g. rest_route (not a regex). With a path, BOTH must match.'
     })
         .option('app', {
         alias: 'a',
@@ -28,13 +33,17 @@ const waf_sink = {
         .option('force', {
         type: 'boolean',
         default: false,
-        description: 'Accept a user-agent that also matches a known search/AI crawler or uptime monitor'
+        description: 'Accept a user-agent that also matches a known search/AI crawler or uptime monitor, or a query parameter that carries an auth flow'
     })
-        .check(({ pattern, userAgent }) => {
-        if (!pattern && !userAgent) {
-            throw new Error('Give a path pattern, --user-agent, or both.\n' +
+        .check(({ pattern, userAgent, query }) => {
+        if (userAgent && query) {
+            throw new Error('A rule can combine a path with --user-agent OR with --query, not both.');
+        }
+        if (!pattern && !userAgent && !query) {
+            throw new Error('Give a path pattern, --user-agent, --query, or a path with one of them.\n' +
                 "  e.g. faable deploy waf sink '^/wp-admin'\n" +
-                '       faable deploy waf sink --user-agent YisouSpider');
+                '       faable deploy waf sink --user-agent YisouSpider\n' +
+                '       faable deploy waf sink --query rest_route');
         }
         return true;
     })
@@ -55,6 +64,7 @@ const waf_sink = {
             app_url: app.url,
             pattern: args.pattern,
             user_agent: args.userAgent,
+            query: args.query,
             action: 'sink',
             description: args.description,
             force: args.force

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faable/faable",
-  "version": "3.1.1",
+  "version": "3.2.0",
   "main": "dist/index.js",
   "license": "MIT",
   "author": "Marc Pomar <marc@faable.com>",