@faable/faable 4.30.1 → 4.31.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -534,6 +534,17 @@ class FaableApi {
534
534
  async addAppWafRule(app_id, params) {
535
535
  return data(this.client.post(`/app/${app_id}/waf/rules`, params));
536
536
  }
537
+ /**
538
+ * What the app's `monitor` rules WOULD have stopped (GET /app/:id/waf/activity,
539
+ * `would_block`): the same rules checked against the traffic it served.
540
+ * Absent on a server without monitor rules, or for an app with none.
541
+ */
542
+ async appWafWouldBlock(app_id, from, to) {
543
+ const body = await data(this.client.get(`/app/${app_id}/waf/activity`, {
544
+ params: { from, to, interval: 86400 }
545
+ }));
546
+ return body;
547
+ }
537
548
  async removeAppWafRule(app_id, params) {
538
549
  return data(this.client.delete(`/app/${app_id}/waf/rules`, {
539
550
  data: params
@@ -77,6 +77,32 @@ const add_rule = async (opts) => {
77
77
  log.info(`Undo: faable deploy waf rm ${undo_args(want)} --action allow -a ${app_id}`);
78
78
  return waf;
79
79
  }
80
+ if (action === 'monitor') {
81
+ log.info(`👀 ${describe_selector(want)} → monitor only, nothing is blocked`);
82
+ log.info(` for ${app_name} (${app_id}).`);
83
+ log.info(``);
84
+ // It reads the past: the rule is checked against traffic already served,
85
+ // so its first answer is the last week, not a week from now.
86
+ const now = Math.floor(Date.now() / 1000);
87
+ const seen = await api
88
+ .appWafWouldBlock(app_id, now - 7 * 86400, now)
89
+ .catch(() => undefined);
90
+ const legend = seen?.rules ?? [];
91
+ const id = legend.find(r => rule_matches_request(r, want, 'monitor'))?.id;
92
+ const n = id
93
+ ? (seen?.would_block?.top_rules.find(r => r.rule === id)?.requests ?? 0)
94
+ : undefined;
95
+ if (n !== undefined) {
96
+ log.info(n === 0
97
+ ? `In the last 7 days it would have stopped nothing.`
98
+ : `In the last 7 days it would have stopped ${n.toLocaleString()} request${n === 1 ? '' : 's'} your app served.`);
99
+ }
100
+ log.info(`The Firewall tab of the app shows what it would stop, request by request.`);
101
+ log.info(``);
102
+ log.info(`When it only catches what it should: faable deploy waf block ${undo_args(want)} -a ${app_id}`);
103
+ log.info(`Undo: faable deploy waf rm ${undo_args(want)} --action monitor -a ${app_id}`);
104
+ return waf;
105
+ }
80
106
  const answer = action === 'deny' ? '403' : '404';
81
107
  log.info(`🛡️ ${describe_selector(want)} → ${answer} at the edge`);
82
108
  log.info(` for ${app_name} (${app_id}).`);
@@ -7,7 +7,9 @@ const action_label = (action) => action === 'sink'
7
7
  ? 'answered by Faable, app not woken (uptime monitors)'
8
8
  : action === 'allow'
9
9
  ? 'allowed (reaches your app where Faable blocks it for every app)'
10
- : action;
10
+ : action === 'monitor'
11
+ ? 'monitor only (nothing blocked; the Firewall tab shows what it would stop)'
12
+ : action;
11
13
  /**
12
14
  * Render the effective WAF of an app.
13
15
  *
@@ -1,6 +1,7 @@
1
1
  import { waf_allow } from './allow.js';
2
2
  import { waf_block } from './block.js';
3
3
  import { waf_list } from './list.js';
4
+ import { waf_monitor } from './monitor.js';
4
5
  import { waf_rm } from './rm.js';
5
6
  import { waf_sink } from './sink.js';
6
7
 
@@ -11,9 +12,10 @@ const waf = {
11
12
  .command(waf_list)
12
13
  .command(waf_block)
13
14
  .command(waf_sink)
15
+ .command(waf_monitor)
14
16
  .command(waf_allow)
15
17
  .command(waf_rm)
16
- .demandCommand(1, 'Specify a waf command: list, block, sink, allow or rm'),
18
+ .demandCommand(1, 'Specify a waf command: list, block, sink, monitor, allow or rm'),
17
19
  handler: () => {
18
20
  // Unreachable: demandCommand(1) either routes to a subcommand or fails
19
21
  // through the global .fail() in src/index.ts.
@@ -0,0 +1,81 @@
1
+ import { requireApi } from '../../../api/context.js';
2
+ import { print_json, json_option } from '../../../lib/listing.js';
3
+ import { resolve_app_id } from '../resolve_app_id.js';
4
+ import { add_rule } from './add_rule.js';
5
+
6
+ const waf_monitor = {
7
+ command: 'monitor [pattern]',
8
+ describe: 'Watch what a rule would stop, without blocking anything (try it before `block`)',
9
+ builder: yargs => json_option(yargs)
10
+ .positional('pattern', {
11
+ type: 'string',
12
+ description: 'Anchored path regex, e.g. ^/admin (quote it in your shell)'
13
+ })
14
+ .option('user-agent', {
15
+ alias: 'u',
16
+ type: 'string',
17
+ description: 'RE2 fragment matched against User-Agent, e.g. YisouSpider. With a path, BOTH must match.'
18
+ })
19
+ .option('query', {
20
+ alias: 'q',
21
+ type: 'string',
22
+ description: 'Literal query parameter name, e.g. rest_route (not a regex). With a path, BOTH must match.'
23
+ })
24
+ .option('app', {
25
+ alias: 'a',
26
+ type: 'string',
27
+ description: 'App id, name or slug (defaults to the linked app)'
28
+ })
29
+ .option('description', {
30
+ alias: 'd',
31
+ type: 'string',
32
+ description: 'Why this rule exists (shown in `waf list`)'
33
+ })
34
+ .option('force', {
35
+ type: 'boolean',
36
+ default: false,
37
+ 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'
38
+ })
39
+ .check(({ pattern, userAgent, query }) => {
40
+ if (userAgent && query) {
41
+ throw new Error('A rule can combine a path with --user-agent OR with --query, not both.');
42
+ }
43
+ if (!pattern && !userAgent && !query) {
44
+ throw new Error('Give a path pattern, --user-agent, --query, or a path with one of them.\n' +
45
+ " e.g. faable deploy waf monitor '^/admin'\n" +
46
+ ' faable deploy waf monitor --user-agent YisouSpider\n' +
47
+ ' faable deploy waf monitor --query rest_route');
48
+ }
49
+ return true;
50
+ })
51
+ .example("$0 deploy waf monitor '^/admin'", 'See which requests a block on /admin would refuse, before refusing any')
52
+ .example('$0 deploy waf monitor --user-agent python-requests', 'Check that a user-agent rule would only catch the clients you mean')
53
+ .epilogue('A monitor rule blocks nothing: every request still reaches your app. ' +
54
+ 'Faable checks it against the traffic your app served, the past ' +
55
+ 'included, and the Firewall tab shows what it would have stopped. ' +
56
+ 'When it only catches what it should, add the same rule with `block` ' +
57
+ 'or `sink` and remove the monitor one.')
58
+ .showHelpOnFail(false),
59
+ handler: async (args) => {
60
+ const ctx = await requireApi();
61
+ const app_id = await resolve_app_id(args.app, ctx.appId, ctx.api);
62
+ const app = await ctx.api.getApp(app_id);
63
+ const waf = await add_rule({
64
+ api: ctx.api,
65
+ app_id,
66
+ app_name: app.name,
67
+ app_url: app.url,
68
+ pattern: args.pattern,
69
+ user_agent: args.userAgent,
70
+ query: args.query,
71
+ action: 'monitor',
72
+ description: args.description,
73
+ force: args.force,
74
+ json: args.json
75
+ });
76
+ if (args.json)
77
+ print_json(waf);
78
+ }
79
+ };
80
+
81
+ export { waf_monitor };
@@ -27,7 +27,7 @@ const waf_rm = {
27
27
  })
28
28
  .option('action', {
29
29
  type: 'string',
30
- choices: ['deny', 'sink', 'allow'],
30
+ choices: ['deny', 'sink', 'allow', 'monitor'],
31
31
  description: 'Only needed when the same rule exists as both'
32
32
  })
33
33
  .option('app', {
@@ -61,7 +61,9 @@ const waf_rm = {
61
61
  user_agent: args.userAgent,
62
62
  query: args.query
63
63
  })} from ${app.name} (${app_id}).`);
64
- log.info(`They reach your app again within ~20s, once the edge picks up the change.`);
64
+ log.info(args.action === 'monitor'
65
+ ? `It never blocked anything: those requests kept reaching your app.`
66
+ : `They reach your app again within ~20s, once the edge picks up the change.`);
65
67
  }
66
68
  };
67
69
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@faable/faable",
3
- "version": "4.30.1",
3
+ "version": "4.31.1",
4
4
  "main": "dist/index.js",
5
5
  "license": "MIT",
6
6
  "author": "Marc Pomar <marc@faable.com>",