pywrit 0.2.8__tar.gz → 0.2.10__tar.gz

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.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: pywrit
3
- Version: 0.2.8
3
+ Version: 0.2.10
4
4
  Summary: Python client + CLI for Writ — the gate before the write
5
5
  License-Expression: MIT
6
6
  Project-URL: Homepage, https://github.com/withwrit/pywrit
@@ -151,10 +151,20 @@ optional extra (tree-sitter based):
151
151
  Without the extra, the scanner prints a one-line hint and keeps going —
152
152
  Python scanning never needs it.
153
153
 
154
+ Findings from non-product paths (docs/, scripts/, sandbox/, examples/,
155
+ benchmark/, demo/, and build-tooling files such as gulpfile.js or
156
+ webpack.config.*) are suppressed by default: the report counts them per
157
+ class and names every suppressed path instead of listing them as findings.
158
+ Pass `--include-non-product` to report them like any other finding.
159
+
154
160
  TS/JS is **scan-only**: findings are listed with verbs for your policy file,
155
161
  but `writ scan --apply` never rewrites TS/JS files — gate those by hand.
156
162
  Covered patterns: `fetch`/`axios` writes, `fs` writes, SQL through knex-style
157
- clients, Prisma writes, and JS SDK calls such as `stripe.refunds.create(...)`.
163
+ clients, Prisma writes, JS SDK calls such as `stripe.refunds.create(...)`, and
164
+ generated REST resource clients: `create` / `update` / `patch` / `remove`
165
+ methods (plus their `...WithHttpInfo` variants) that build request options
166
+ with an explicit write HTTP method and route them through the client request
167
+ pipeline (twilio-style generated clients, e.g. `twilio-node`).
158
168
  (Still not covered: the *Python* SDK equivalents like `stripe.Refund.create(...)`
159
169
  — see "Not covered" above.)
160
170
 
@@ -177,11 +187,19 @@ job summary. The check fails when an ungated finding meets your
177
187
  No API key needed. Full reference: [docs/github-action.md](docs/github-action.md) ·
178
188
  example workflow: [examples/github-action/writ-scan.yml](examples/github-action/writ-scan.yml)
179
189
 
190
+ ## GitHub App
191
+
192
+ Install the [Writ GitHub App](https://github.com/apps/writ-scanner) on selected
193
+ repositories: every push and pull request is scanned for ungated write-sites,
194
+ with results as a check run on the PR and in the
195
+ [portal](https://app.withwrit.com), where you manage policy, keys, and the audit log.
196
+ Setup and data handling: [GitHub App docs](https://docs.withwrit.com/git-hub-app).
197
+
180
198
  ## MCP server (`writ-mcp`)
181
199
 
182
200
  Give any MCP-compatible agent point-of-action policy checks. `writ-mcp` is a
183
201
  [Model Context Protocol](https://modelcontextprotocol.io) server (stdio transport,
184
- built on the MCP Python SDK) that exposes the Writ gate as **8 MCP tools**:
202
+ built on the MCP Python SDK) that exposes the Writ gate as **17 MCP tools**:
185
203
  the agent calls `writ_check` before a consequential write and gets back `ALLOW`,
186
204
  `DENY`, or `STEP_UP` — with a tamper-evident, hash-chained audit receipt for
187
205
  every decision.
@@ -201,13 +219,21 @@ pip install writ-mcp # then run `writ-mcp`
201
219
  | `writ_receipts` | Read the tenant's audit log |
202
220
  | `writ_policy` | Manage the verb policy |
203
221
  | `writ_sandbox` | Keyless 90-second demo grant — no API key needed |
222
+ | `writ_github_installations` | List connected GitHub App installations |
223
+ | `writ_github_set_threshold` | Set the check-run fail threshold per install |
224
+ | `writ_github_toggle_pr_comments` | Enable/disable the PR-comment bot |
225
+ | `writ_manifests` | List repos with risk profiles or fetch one manifest |
226
+ | `writ_explain_receipt` | Explain a receipt in plain language |
227
+ | `writ_tenant_notify` | Get or update step-up notification settings |
228
+ | `writ_principals` | List the tenant's principals |
229
+ | `writ_verbs` | List the tenant's verb vocabulary |
230
+ | `writ_keys` | List API key metadata |
204
231
 
205
232
  The gate tools need a free Writ API key (`WRIT_API_KEY`): 10,000 receipts/month
206
233
  free, no credit card. `writ_sandbox` works with no key at all.
207
234
 
208
235
  The server implementation lives in [`mcp/`](mcp/) (MIT). Also published on the
209
- official MCP Registry as `io.github.withwrit/writ`, on
210
- [Smithery](https://smithery.ai/server/withwrit/writ-mcp), and listed on
236
+ official MCP Registry as `io.github.withwrit/writ` and listed on
211
237
  [Glama](https://glama.ai/mcp/servers/withwrit/pywrit).
212
238
 
213
239
  ## Python client
@@ -129,10 +129,20 @@ optional extra (tree-sitter based):
129
129
  Without the extra, the scanner prints a one-line hint and keeps going —
130
130
  Python scanning never needs it.
131
131
 
132
+ Findings from non-product paths (docs/, scripts/, sandbox/, examples/,
133
+ benchmark/, demo/, and build-tooling files such as gulpfile.js or
134
+ webpack.config.*) are suppressed by default: the report counts them per
135
+ class and names every suppressed path instead of listing them as findings.
136
+ Pass `--include-non-product` to report them like any other finding.
137
+
132
138
  TS/JS is **scan-only**: findings are listed with verbs for your policy file,
133
139
  but `writ scan --apply` never rewrites TS/JS files — gate those by hand.
134
140
  Covered patterns: `fetch`/`axios` writes, `fs` writes, SQL through knex-style
135
- clients, Prisma writes, and JS SDK calls such as `stripe.refunds.create(...)`.
141
+ clients, Prisma writes, JS SDK calls such as `stripe.refunds.create(...)`, and
142
+ generated REST resource clients: `create` / `update` / `patch` / `remove`
143
+ methods (plus their `...WithHttpInfo` variants) that build request options
144
+ with an explicit write HTTP method and route them through the client request
145
+ pipeline (twilio-style generated clients, e.g. `twilio-node`).
136
146
  (Still not covered: the *Python* SDK equivalents like `stripe.Refund.create(...)`
137
147
  — see "Not covered" above.)
138
148
 
@@ -155,11 +165,19 @@ job summary. The check fails when an ungated finding meets your
155
165
  No API key needed. Full reference: [docs/github-action.md](docs/github-action.md) ·
156
166
  example workflow: [examples/github-action/writ-scan.yml](examples/github-action/writ-scan.yml)
157
167
 
168
+ ## GitHub App
169
+
170
+ Install the [Writ GitHub App](https://github.com/apps/writ-scanner) on selected
171
+ repositories: every push and pull request is scanned for ungated write-sites,
172
+ with results as a check run on the PR and in the
173
+ [portal](https://app.withwrit.com), where you manage policy, keys, and the audit log.
174
+ Setup and data handling: [GitHub App docs](https://docs.withwrit.com/git-hub-app).
175
+
158
176
  ## MCP server (`writ-mcp`)
159
177
 
160
178
  Give any MCP-compatible agent point-of-action policy checks. `writ-mcp` is a
161
179
  [Model Context Protocol](https://modelcontextprotocol.io) server (stdio transport,
162
- built on the MCP Python SDK) that exposes the Writ gate as **8 MCP tools**:
180
+ built on the MCP Python SDK) that exposes the Writ gate as **17 MCP tools**:
163
181
  the agent calls `writ_check` before a consequential write and gets back `ALLOW`,
164
182
  `DENY`, or `STEP_UP` — with a tamper-evident, hash-chained audit receipt for
165
183
  every decision.
@@ -179,13 +197,21 @@ pip install writ-mcp # then run `writ-mcp`
179
197
  | `writ_receipts` | Read the tenant's audit log |
180
198
  | `writ_policy` | Manage the verb policy |
181
199
  | `writ_sandbox` | Keyless 90-second demo grant — no API key needed |
200
+ | `writ_github_installations` | List connected GitHub App installations |
201
+ | `writ_github_set_threshold` | Set the check-run fail threshold per install |
202
+ | `writ_github_toggle_pr_comments` | Enable/disable the PR-comment bot |
203
+ | `writ_manifests` | List repos with risk profiles or fetch one manifest |
204
+ | `writ_explain_receipt` | Explain a receipt in plain language |
205
+ | `writ_tenant_notify` | Get or update step-up notification settings |
206
+ | `writ_principals` | List the tenant's principals |
207
+ | `writ_verbs` | List the tenant's verb vocabulary |
208
+ | `writ_keys` | List API key metadata |
182
209
 
183
210
  The gate tools need a free Writ API key (`WRIT_API_KEY`): 10,000 receipts/month
184
211
  free, no credit card. `writ_sandbox` works with no key at all.
185
212
 
186
213
  The server implementation lives in [`mcp/`](mcp/) (MIT). Also published on the
187
- official MCP Registry as `io.github.withwrit/writ`, on
188
- [Smithery](https://smithery.ai/server/withwrit/writ-mcp), and listed on
214
+ official MCP Registry as `io.github.withwrit/writ` and listed on
189
215
  [Glama](https://glama.ai/mcp/servers/withwrit/pywrit).
190
216
 
191
217
  ## Python client
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "pywrit"
7
- version = "0.2.8"
7
+ version = "0.2.10"
8
8
  description = "Python client + CLI for Writ — the gate before the write"
9
9
  readme = "README.md"
10
10
  license = "MIT"
@@ -27,7 +27,7 @@ from .errors import (
27
27
  WritError,
28
28
  )
29
29
 
30
- __version__ = "0.2.8"
30
+ __version__ = "0.2.10"
31
31
 
32
32
  __all__ = [
33
33
  "WritClient",
@@ -826,6 +826,54 @@ _TSJS_EXTS = {".ts": "typescript", ".tsx": "tsx", ".js": "javascript",
826
826
  _TSJS_SKIP_DIR_NAMES = _SKIP_DIR_NAMES | {".next", "vendor", "venv", ".venv"}
827
827
  _TSJS_TEST_DIRS = {"tests", "testing", "__tests__"}
828
828
  _TSJS_MAX_BYTES = 1000000 # larger files are almost always bundles
829
+
830
+ # Non-product path classes. Write findings from these paths parse as real
831
+ # writes but are almost never product behavior — docs tooling, build/test
832
+ # scripts, demos, benchmarks (the axios-class scan noise: gulpfile.js,
833
+ # docs/scripts/*, sandbox/*, scripts/benchmark-*). They are suppressed from
834
+ # the report by default — counted per class under "suppressed" — and
835
+ # restored with --include-non-product. Matching is by whole directory
836
+ # segment or exact build-file basename, never filename substring, so
837
+ # product code next to an excluded directory (and files like
838
+ # lib/benchmark-utils.ts) stays reported. This is the single, central
839
+ # exclusion list for TS/JS; don't scatter string matches elsewhere.
840
+ _TSJS_NON_PRODUCT_DIRS = {
841
+ "docs": {"docs", "doc"},
842
+ "scripts": {"scripts"},
843
+ "examples": {"examples", "example"},
844
+ "sandbox": {"sandbox"},
845
+ "benchmark": {"benchmark", "benchmarks"},
846
+ "demo": {"demo", "demos"},
847
+ }
848
+ _TSJS_BUILD_TOOL_FILE = _re.compile(
849
+ r"^(gulpfile|gruntfile)(\.babel)?\.(js|mjs|cjs|ts)$"
850
+ r"|^(webpack|rollup|vite|esbuild|tsup|snowpack|babel)\.config\.(js|mjs|cjs|ts)$"
851
+ r"|^karma\.conf\.(js|mjs|cjs|ts)$", _re.I)
852
+
853
+
854
+ def _tsjs_non_product_class(path, root):
855
+ """Return the non-product path class for a TS/JS file, or None.
856
+
857
+ Directory classes match on whole path segments (docs/, scripts/,
858
+ sandbox/, examples/, benchmark/, demo/ at any depth), so a product
859
+ file beside an excluded directory is unaffected. Build-tooling files
860
+ (gulpfile.js, Gruntfile.js, webpack.config.*, rollup.config.*,
861
+ vite.config.*, and equivalents) match by exact basename anywhere in
862
+ the tree so monorepo package configs are covered too.
863
+ """
864
+ rel = path.relative_to(root)
865
+ segs = set(rel.parts[:-1])
866
+ for cls, names in _TSJS_NON_PRODUCT_DIRS.items():
867
+ if segs & names:
868
+ return cls
869
+ if _TSJS_BUILD_TOOL_FILE.match(path.name):
870
+ return "build-tooling"
871
+ return None
872
+
873
+
874
+ def _tsjs_suppressed_total(suppressed):
875
+ """Total suppressed sites across all non-product classes."""
876
+ return sum(b["sites"] for b in (suppressed or {}).values())
829
877
  _TSJS_HINT = ("hint: %d TS/JS file(s) not scanned; install the extra: "
830
878
  "pip install 'pywrit[polyglot]'")
831
879
  _TSJS_WRITE_METHODS = {"post", "put", "patch", "delete"}
@@ -860,7 +908,10 @@ _TSJS_HTTP_VERBS = "post|put|patch|delete|del"
860
908
  # Patterns are dotted callee chains (after import aliasing and dropping a
861
909
  # leading `this`): `a|b` alternatives, `*` one segment, `**` any segments.
862
910
  # Conditions: None, "method" (a literal write method in an options object
863
- # or as a leading string arg), "sql" (first arg is a literal SQL write).
911
+ # or as a leading string arg), "sql" (first arg is a literal SQL write),
912
+ # "resource_write" (generated REST resource method: the enclosing
913
+ # create/update/patch/remove-style method routes a request that carries an
914
+ # explicit write HTTP method; reads never match).
864
915
  _TSJS_RULES = (
865
916
  ("child-process", "exec",
866
917
  ("child_process.exec|execSync|execFile|execFileSync|spawn|spawnSync|"
@@ -886,6 +937,14 @@ _TSJS_RULES = (
886
937
  ("http-config-write", "http",
887
938
  ("axios|got|ky|superagent", "axios|got|ky.request",
888
939
  "http|https.request"), "method"),
940
+ # Generated REST resource clients (twilio-style): resource methods named
941
+ # create/update/patch/remove (+ ...WithHttpInfo) that build request
942
+ # options with an explicit write HTTP method and route them through the
943
+ # client request pipeline (Version.request / Domain.request). The
944
+ # callee is the pipeline, so the pattern is unanchored and the condition
945
+ # does the work: it never fires on method: "get" or read-named methods
946
+ # (fetch/list/page/stream/each).
947
+ ("resource-write", "http", ("**",), "resource_write"),
889
948
  )
890
949
 
891
950
 
@@ -1176,7 +1235,37 @@ def _tsjs_has_write_method(call, f):
1176
1235
  return False
1177
1236
 
1178
1237
 
1179
- def _tsjs_classify(call, chain, f):
1238
+ _TSJS_RESOURCE_WRITE_NAMES = frozenset(
1239
+ ("create", "update", "patch", "remove", "del", "delete"))
1240
+ _TSJS_HTTPINFO_SUFFIX = "withhttpinfo"
1241
+
1242
+
1243
+ def _tsjs_resource_write_func(func_name):
1244
+ """True for generated-REST-resource write methods: create/update/patch/
1245
+ remove (plus del/delete variants) and their ...WithHttpInfo forms.
1246
+ Read-style names (fetch/list/page/stream/each/get) never match."""
1247
+ if not func_name:
1248
+ return False
1249
+ n = func_name.lower()
1250
+ if n.endswith(_TSJS_HTTPINFO_SUFFIX):
1251
+ n = n[:-len(_TSJS_HTTPINFO_SUFFIX)]
1252
+ return n in _TSJS_RESOURCE_WRITE_NAMES
1253
+
1254
+
1255
+ def _tsjs_resource_write(call, func_name, f):
1256
+ """Generated-resource write: inside a create/update/patch/remove-style
1257
+ method, a request that carries an explicit write HTTP method (a literal
1258
+ `method: "post"`-style options key, or the method as a leading string
1259
+ arg) routed through a call. The callee is the request pipeline and may
1260
+ be any name (operationVersion.update, this.request, Version.fetch for
1261
+ DELETE-that-returns-a-body), so only the literal decides write-vs-read:
1262
+ `method: "get"` is never a write and read-named enclosing methods never
1263
+ match."""
1264
+ return _tsjs_resource_write_func(func_name) and \
1265
+ _tsjs_has_write_method(call, f)
1266
+
1267
+
1268
+ def _tsjs_classify(call, chain, f, func_name):
1180
1269
  for rid, kind, pats, cond in _TSJS_COMPILED:
1181
1270
  if not any(_tsjs_glob(p, chain) for p in pats):
1182
1271
  continue
@@ -1187,6 +1276,9 @@ def _tsjs_classify(call, chain, f):
1187
1276
  lit = f.literal(args[0]) if args else None
1188
1277
  if lit is None or not _TSJS_SQL_WRITE.match(lit):
1189
1278
  continue
1279
+ if cond == "resource_write" and \
1280
+ not _tsjs_resource_write(call, func_name, f):
1281
+ continue
1190
1282
  return rid, kind
1191
1283
  return None
1192
1284
 
@@ -1229,7 +1321,7 @@ def _tsjs_scan_source(src, filename, parser):
1229
1321
  if chain[-1] in _TSJS_GATE_NAMES:
1230
1322
  gated.add(fkey)
1231
1323
  continue
1232
- hit = _tsjs_classify(node, chain, f)
1324
+ hit = _tsjs_classify(node, chain, f, fkey[0])
1233
1325
  if hit:
1234
1326
  snippet = " ".join(f.text(node).split())[:100]
1235
1327
  sites.append((_WriteSite(filename, fkey[0], cls,
@@ -1245,12 +1337,17 @@ def _tsjs_verb(rel, func_name, cls_name, kind):
1245
1337
  return infer_verb(base, snake, cls_name, kind)
1246
1338
 
1247
1339
 
1248
- def _tsjs_scan(root, excludes):
1249
- """Return dict with files, skipped, sites, gated, or hint when the
1250
- extra is missing. Never raises on a bad file."""
1340
+ def _tsjs_scan(root, excludes, include_non_product=False):
1341
+ """Return dict with files, skipped, sites, gated, suppressed, or hint
1342
+ when the extra is missing. Never raises on a bad file.
1343
+
1344
+ Findings from non-product paths (_tsjs_non_product_class) are not
1345
+ dropped — they are counted per path class in res["suppressed"] so the
1346
+ report can say exactly what was held back. include_non_product restores
1347
+ the old behavior of reporting every site."""
1251
1348
  files = _tsjs_collect_files(root, excludes)
1252
1349
  res = {"files": files, "skipped": [], "sites": [], "gated": set(),
1253
- "missing_extra": False}
1350
+ "suppressed": {}, "missing_extra": False}
1254
1351
  if not files:
1255
1352
  return res
1256
1353
  parsers = _tsjs_parsers()
@@ -1268,6 +1365,14 @@ def _tsjs_scan(root, excludes):
1268
1365
  except Exception:
1269
1366
  res["skipped"].append(str(path))
1270
1367
  continue
1368
+ cls = None if include_non_product \
1369
+ else _tsjs_non_product_class(path, root)
1370
+ if cls is not None and sites:
1371
+ bucket = res["suppressed"].setdefault(
1372
+ cls, {"sites": 0, "files": {}})
1373
+ bucket["sites"] += len(sites)
1374
+ bucket["files"][str(path)] = len(sites)
1375
+ continue
1271
1376
  res["sites"].extend(sites)
1272
1377
  res["gated"].update((str(path),) + g for g in gated)
1273
1378
  return res
@@ -1331,10 +1436,24 @@ def print_scan_json(root, files, skipped, sites, gated_funcs, tsjs, ts_sites):
1331
1436
  "findings": _scan_findings_json(root, sites, gated_funcs, tsjs,
1332
1437
  ts_sites),
1333
1438
  }
1439
+ ts_suppressed = tsjs.get("suppressed") or {}
1440
+ ts_sup_total = _tsjs_suppressed_total(ts_suppressed)
1441
+ if ts_sup_total:
1442
+ # Non-product findings held back by default: never dropped
1443
+ # silently — the report names every suppressed path.
1444
+ doc["tsjs_suppressed_non_product"] = {
1445
+ "sites": ts_sup_total,
1446
+ "by_class": {c: ts_suppressed[c]["sites"]
1447
+ for c in sorted(ts_suppressed)},
1448
+ "files": sorted(
1449
+ str(_pathlib.Path(f).relative_to(root))
1450
+ for c in ts_suppressed.values()
1451
+ for f in c["files"]),
1452
+ }
1334
1453
  print(json.dumps(doc, indent=2))
1335
1454
 
1336
1455
 
1337
- def _scan_repo(root, excludes):
1456
+ def _scan_repo(root, excludes, include_non_product=False):
1338
1457
  """Collect Python and TS/JS files and find write sites.
1339
1458
 
1340
1459
  Returns (files, skipped, sites, gated, tsjs). This is the read-only
@@ -1358,7 +1477,8 @@ def _scan_repo(root, excludes):
1358
1477
  sites.extend(v.sites)
1359
1478
  gated.update((str(path), n, ln) for (n, ln) in v.gated)
1360
1479
 
1361
- tsjs = _tsjs_scan(root, excludes or [])
1480
+ tsjs = _tsjs_scan(root, excludes or [],
1481
+ include_non_product=include_non_product)
1362
1482
  return files, skipped, sites, gated, tsjs
1363
1483
 
1364
1484
 
@@ -1472,7 +1592,9 @@ def scan_cmd(args):
1472
1592
  print("error: not a directory: %s" % args.path, file=sys.stderr)
1473
1593
  return 2
1474
1594
 
1475
- files, skipped, sites, gated, tsjs = _scan_repo(root, args.exclude or [])
1595
+ files, skipped, sites, gated, tsjs = _scan_repo(
1596
+ root, args.exclude or [],
1597
+ include_non_product=getattr(args, "include_non_product", False))
1476
1598
  analysis = _analyze_scan(root, files, skipped, sites, gated, tsjs)
1477
1599
  by_func = analysis["by_func"]
1478
1600
  ts_by_func = analysis["ts_by_func"]
@@ -1516,6 +1638,19 @@ def scan_cmd(args):
1516
1638
  print(" %s:%d [%s] %s %s(): %s" % (
1517
1639
  _pathlib.Path(s.file).relative_to(root), s.lineno, s.kind,
1518
1640
  rid, s.func or "<module>", s.snippet))
1641
+ suppressed = tsjs.get("suppressed") or {}
1642
+ sup_total = _tsjs_suppressed_total(suppressed)
1643
+ if sup_total:
1644
+ by_class = ", ".join("%s: %d" % (c, suppressed[c]["sites"])
1645
+ for c in sorted(suppressed))
1646
+ print(" ts/js non-product: %d site(s) suppressed (%s); "
1647
+ "re-run with --include-non-product to show them"
1648
+ % (sup_total, by_class))
1649
+ for cls in sorted(suppressed):
1650
+ for f in sorted(suppressed[cls]["files"]):
1651
+ print(" suppressed %s: %d site(s) [%s]" % (
1652
+ _pathlib.Path(f).relative_to(root),
1653
+ suppressed[cls]["files"][f], cls))
1519
1654
  if verbs:
1520
1655
  print(" verbs discovered: %d" % len(verbs))
1521
1656
  for vname in sorted(verbs):
@@ -2094,6 +2229,13 @@ def main():
2094
2229
  help="Output format: human-readable text (default) or "
2095
2230
  "machine-readable JSON risk report (read-only; no "
2096
2231
  "policy file, no diffs)")
2232
+ scan.add_argument("--include-non-product", action="store_true",
2233
+ help="Include TS/JS findings from non-product paths that the "
2234
+ "scan suppresses by default: docs/, scripts/, sandbox/, "
2235
+ "examples/, benchmark/, demo/ directories and "
2236
+ "build-tooling files (gulpfile.js, webpack.config.*, "
2237
+ "rollup.config.*, vite.config.*, ...). Suppressed sites "
2238
+ "are always reported as a per-class count.")
2097
2239
  scan.add_argument("--push-policy", action="store_true",
2098
2240
  help="PUT the discovered policy to the gate (needs --key)")
2099
2241
  scan.add_argument("--key", default="",
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: pywrit
3
- Version: 0.2.8
3
+ Version: 0.2.10
4
4
  Summary: Python client + CLI for Writ — the gate before the write
5
5
  License-Expression: MIT
6
6
  Project-URL: Homepage, https://github.com/withwrit/pywrit
@@ -151,10 +151,20 @@ optional extra (tree-sitter based):
151
151
  Without the extra, the scanner prints a one-line hint and keeps going —
152
152
  Python scanning never needs it.
153
153
 
154
+ Findings from non-product paths (docs/, scripts/, sandbox/, examples/,
155
+ benchmark/, demo/, and build-tooling files such as gulpfile.js or
156
+ webpack.config.*) are suppressed by default: the report counts them per
157
+ class and names every suppressed path instead of listing them as findings.
158
+ Pass `--include-non-product` to report them like any other finding.
159
+
154
160
  TS/JS is **scan-only**: findings are listed with verbs for your policy file,
155
161
  but `writ scan --apply` never rewrites TS/JS files — gate those by hand.
156
162
  Covered patterns: `fetch`/`axios` writes, `fs` writes, SQL through knex-style
157
- clients, Prisma writes, and JS SDK calls such as `stripe.refunds.create(...)`.
163
+ clients, Prisma writes, JS SDK calls such as `stripe.refunds.create(...)`, and
164
+ generated REST resource clients: `create` / `update` / `patch` / `remove`
165
+ methods (plus their `...WithHttpInfo` variants) that build request options
166
+ with an explicit write HTTP method and route them through the client request
167
+ pipeline (twilio-style generated clients, e.g. `twilio-node`).
158
168
  (Still not covered: the *Python* SDK equivalents like `stripe.Refund.create(...)`
159
169
  — see "Not covered" above.)
160
170
 
@@ -177,11 +187,19 @@ job summary. The check fails when an ungated finding meets your
177
187
  No API key needed. Full reference: [docs/github-action.md](docs/github-action.md) ·
178
188
  example workflow: [examples/github-action/writ-scan.yml](examples/github-action/writ-scan.yml)
179
189
 
190
+ ## GitHub App
191
+
192
+ Install the [Writ GitHub App](https://github.com/apps/writ-scanner) on selected
193
+ repositories: every push and pull request is scanned for ungated write-sites,
194
+ with results as a check run on the PR and in the
195
+ [portal](https://app.withwrit.com), where you manage policy, keys, and the audit log.
196
+ Setup and data handling: [GitHub App docs](https://docs.withwrit.com/git-hub-app).
197
+
180
198
  ## MCP server (`writ-mcp`)
181
199
 
182
200
  Give any MCP-compatible agent point-of-action policy checks. `writ-mcp` is a
183
201
  [Model Context Protocol](https://modelcontextprotocol.io) server (stdio transport,
184
- built on the MCP Python SDK) that exposes the Writ gate as **8 MCP tools**:
202
+ built on the MCP Python SDK) that exposes the Writ gate as **17 MCP tools**:
185
203
  the agent calls `writ_check` before a consequential write and gets back `ALLOW`,
186
204
  `DENY`, or `STEP_UP` — with a tamper-evident, hash-chained audit receipt for
187
205
  every decision.
@@ -201,13 +219,21 @@ pip install writ-mcp # then run `writ-mcp`
201
219
  | `writ_receipts` | Read the tenant's audit log |
202
220
  | `writ_policy` | Manage the verb policy |
203
221
  | `writ_sandbox` | Keyless 90-second demo grant — no API key needed |
222
+ | `writ_github_installations` | List connected GitHub App installations |
223
+ | `writ_github_set_threshold` | Set the check-run fail threshold per install |
224
+ | `writ_github_toggle_pr_comments` | Enable/disable the PR-comment bot |
225
+ | `writ_manifests` | List repos with risk profiles or fetch one manifest |
226
+ | `writ_explain_receipt` | Explain a receipt in plain language |
227
+ | `writ_tenant_notify` | Get or update step-up notification settings |
228
+ | `writ_principals` | List the tenant's principals |
229
+ | `writ_verbs` | List the tenant's verb vocabulary |
230
+ | `writ_keys` | List API key metadata |
204
231
 
205
232
  The gate tools need a free Writ API key (`WRIT_API_KEY`): 10,000 receipts/month
206
233
  free, no credit card. `writ_sandbox` works with no key at all.
207
234
 
208
235
  The server implementation lives in [`mcp/`](mcp/) (MIT). Also published on the
209
- official MCP Registry as `io.github.withwrit/writ`, on
210
- [Smithery](https://smithery.ai/server/withwrit/writ-mcp), and listed on
236
+ official MCP Registry as `io.github.withwrit/writ` and listed on
211
237
  [Glama](https://glama.ai/mcp/servers/withwrit/pywrit).
212
238
 
213
239
  ## Python client
@@ -113,15 +113,16 @@ class FixtureRulesTest(unittest.TestCase):
113
113
  verbs = __import__("json").loads(policy.read_text())
114
114
  self.assertEqual(code, 0)
115
115
  n = len(_expected())
116
- self.assertIn("ts/js files scanned: 7 skipped: 0 (scan only, no --apply)", out)
117
- self.assertIn("ts/js write sites: %d in 11 function(s)" % n, out)
116
+ self.assertIn("ts/js files scanned: 9 skipped: 0 (scan only, no --apply)", out)
117
+ self.assertIn("ts/js write sites: %d in 18 function(s)" % n, out)
118
118
  self.assertIn("ts/js gated: 1/%d" % n, out) # gated.ts calls writCheck
119
119
  self.assertIn(" payments/refunds.service.ts:10 [sdk] stripe-write "
120
120
  "issueRefund(): stripe.refunds.create({ charge: chargeId })", out)
121
121
  self.assertIn(" http.ts:10 [http] fetch-write createOrder(): fetch(url, "
122
122
  "{ method: \"POST\", body: JSON.stringify(body) })", out)
123
123
  for v in ("payments.refund", "payments.record", "payments.export",
124
- "storage.save", "storage.create", "http.create", "legacy.write"):
124
+ "storage.save", "storage.create", "http.create", "legacy.write",
125
+ "rest.create", "rest.update", "rest.delete"):
125
126
  self.assertEqual(verbs.get(v), "require_grant", v)
126
127
  self.assertIn("nothing to instrument (ts/js findings are scan-only", out)
127
128
 
@@ -238,6 +239,68 @@ class FileWalkTest(unittest.TestCase):
238
239
  self.assertEqual(got, ["src/a.ts"])
239
240
 
240
241
 
242
+ class ResourceWriteTest(unittest.TestCase):
243
+ """Regression for generated REST resource clients (twilio-style): the
244
+ fixture has a version request pipeline plus a resource class and a
245
+ factory-pattern list whose create/update/patch/remove methods route
246
+ requests with an explicit write HTTP method. Only those methods are
247
+ findings; fetch/list/get reads (even through pipeline calls) are not."""
248
+
249
+ EXPECTED = {
250
+ ("rest/account.ts", 52, "resource-write"), # update()
251
+ ("rest/account.ts", 56, "resource-write"), # updateWithHttpInfo()
252
+ ("rest/account.ts", 60, "resource-write"), # remove() via Version.fetch
253
+ ("rest/account.ts", 64, "resource-write"), # removeWithHttpInfo()
254
+ ("rest/account.ts", 68, "resource-write"), # patch()
255
+ ("rest/message.ts", 14, "resource-write"), # factory create()
256
+ ("rest/message.ts", 18, "resource-write"), # factory remove()
257
+ }
258
+
259
+ @unittest.skipUnless(HAVE_EXTRA, "polyglot extra not installed")
260
+ def test_fixture_layout_flags_writes_not_reads(self):
261
+ with tempfile.TemporaryDirectory() as td:
262
+ root = _copy_fixtures(pathlib.Path(td) / "repo")
263
+ code, out = _run_scan(root)
264
+ self.assertEqual(code, 0)
265
+ rest = {f for f in _findings(out) if f[0].startswith("rest/")}
266
+ self.assertEqual(rest, self.EXPECTED, out)
267
+
268
+ @unittest.skipUnless(HAVE_EXTRA, "polyglot extra not installed")
269
+ def test_json_mode_reports_resource_finding(self):
270
+ with tempfile.TemporaryDirectory() as td:
271
+ root = pathlib.Path(td) / "repo"
272
+ (root / "rest").mkdir(parents=True)
273
+ (root / "rest" / "account.ts").write_text(
274
+ "class Version {\n"
275
+ " update(opts: any) { return this.request(opts); }\n"
276
+ "}\n"
277
+ "class AccountContext {\n"
278
+ " constructor(private version: Version) {}\n"
279
+ " update() {\n"
280
+ " return this.version.update({ uri: \"/x\", method: \"post\" });\n"
281
+ " }\n"
282
+ " fetch() {\n"
283
+ " return this.version.fetch({ uri: \"/x\", method: \"get\" });\n"
284
+ " }\n"
285
+ "}\n")
286
+ buf = io.StringIO()
287
+ with contextlib.redirect_stdout(buf):
288
+ code = cli.scan_cmd(_args(root, pathlib.Path(td) / "policy.json",
289
+ format="json"))
290
+ out = buf.getvalue()
291
+ self.assertEqual(code, 0)
292
+ doc = __import__("json").loads(out)
293
+ self.assertEqual(doc["files_scanned"], 1)
294
+ findings = doc["findings"]
295
+ self.assertEqual(len(findings), 1, doc)
296
+ f = findings[0]
297
+ self.assertEqual((f["file"], f["line"], f["function"], f["verb"]),
298
+ ("rest/account.ts", 7, "update", "rest.update"))
299
+ self.assertEqual((f["kind"], f["language"], f["gated"]),
300
+ ("http", "tsjs", False))
301
+ self.assertIn('method: "post"', f["snippet"])
302
+
303
+
241
304
  class MissingExtraTest(unittest.TestCase):
242
305
  def test_hint_once_and_python_still_scanned(self):
243
306
  with tempfile.TemporaryDirectory() as td:
@@ -274,6 +337,49 @@ class MissingExtraTest(unittest.TestCase):
274
337
  " orders.create\n" % root.resolve()), out)
275
338
 
276
339
 
340
+ class NonProductScanTest(unittest.TestCase):
341
+ """Axios-class noise: non-product paths are suppressed by default,
342
+ counted per class with paths named, and restored by the flag."""
343
+
344
+ WRITE = 'fetch("https://api.example.com/x", {method: "POST"})\n'
345
+
346
+ def _layout(self, root):
347
+ (root / "lib").mkdir(parents=True)
348
+ (root / "lib" / "core.js").write_text(self.WRITE)
349
+ for d in ("docs/scripts", "scripts", "sandbox", "examples"):
350
+ p = root / d
351
+ p.mkdir(parents=True)
352
+ (p / "tool.js").write_text(self.WRITE)
353
+ (root / "gulpfile.js").write_text(self.WRITE)
354
+ (root / "lib" / "benchmark-utils.ts").write_text(self.WRITE)
355
+
356
+ @unittest.skipUnless(HAVE_EXTRA, "polyglot extra not installed")
357
+ def test_suppressed_by_default_and_restored_by_flag(self):
358
+ with tempfile.TemporaryDirectory() as td:
359
+ root = pathlib.Path(td)
360
+ self._layout(root)
361
+ res = cli._tsjs_scan(root, [])
362
+ self.assertEqual(len(res["sites"]), 2) # lib/core.js + benchmark-utils.ts
363
+ total = cli._tsjs_suppressed_total(res["suppressed"])
364
+ self.assertEqual(total, 5)
365
+ res2 = cli._tsjs_scan(root, [], include_non_product=True)
366
+ self.assertEqual(len(res2["sites"]), 7)
367
+ self.assertEqual(res2["suppressed"], {})
368
+
369
+ def test_path_class_units(self):
370
+ root = pathlib.Path("/repo")
371
+ self.assertEqual(
372
+ cli._tsjs_non_product_class(root / "docs" / "a.js", root), "docs")
373
+ self.assertEqual(
374
+ cli._tsjs_non_product_class(root / "gulpfile.js", root),
375
+ "build-tooling")
376
+ self.assertIsNone(
377
+ cli._tsjs_non_product_class(root / "lib" / "benchmark-utils.ts",
378
+ root))
379
+ self.assertIsNone(
380
+ cli._tsjs_non_product_class(root / "lib" / "core.js", root))
381
+
382
+
277
383
  class CliSyncTest(unittest.TestCase):
278
384
  def test_download_copy_is_byte_identical(self):
279
385
  web = HERE.parent.parent / "gate" / "web" / "writ"
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes