pywrit 0.2.9__tar.gz → 0.2.11__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.
- {pywrit-0.2.9/src/pywrit.egg-info → pywrit-0.2.11}/PKG-INFO +26 -5
- {pywrit-0.2.9 → pywrit-0.2.11}/README.md +25 -4
- {pywrit-0.2.9 → pywrit-0.2.11}/pyproject.toml +1 -1
- {pywrit-0.2.9 → pywrit-0.2.11}/src/pywrit/__init__.py +1 -1
- {pywrit-0.2.9 → pywrit-0.2.11}/src/pywrit/cli.py +129 -8
- {pywrit-0.2.9 → pywrit-0.2.11/src/pywrit.egg-info}/PKG-INFO +26 -5
- {pywrit-0.2.9 → pywrit-0.2.11}/tests/test_scan_tsjs.py +138 -0
- {pywrit-0.2.9 → pywrit-0.2.11}/LICENSE +0 -0
- {pywrit-0.2.9 → pywrit-0.2.11}/setup.cfg +0 -0
- {pywrit-0.2.9 → pywrit-0.2.11}/src/pywrit/client.py +0 -0
- {pywrit-0.2.9 → pywrit-0.2.11}/src/pywrit/errors.py +0 -0
- {pywrit-0.2.9 → pywrit-0.2.11}/src/pywrit.egg-info/SOURCES.txt +0 -0
- {pywrit-0.2.9 → pywrit-0.2.11}/src/pywrit.egg-info/dependency_links.txt +0 -0
- {pywrit-0.2.9 → pywrit-0.2.11}/src/pywrit.egg-info/entry_points.txt +0 -0
- {pywrit-0.2.9 → pywrit-0.2.11}/src/pywrit.egg-info/requires.txt +0 -0
- {pywrit-0.2.9 → pywrit-0.2.11}/src/pywrit.egg-info/top_level.txt +0 -0
- {pywrit-0.2.9 → pywrit-0.2.11}/tests/test_client.py +0 -0
- {pywrit-0.2.9 → pywrit-0.2.11}/tests/test_scan_json.py +0 -0
- {pywrit-0.2.9 → pywrit-0.2.11}/tests/test_scan_python.py +0 -0
- {pywrit-0.2.9 → pywrit-0.2.11}/tests/test_wrap.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: pywrit
|
|
3
|
-
Version: 0.2.
|
|
3
|
+
Version: 0.2.11
|
|
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,6 +151,18 @@ 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
|
+
|
|
160
|
+
Every scan report ends with a one-line pointer to the Writ GitHub App
|
|
161
|
+
(install: https://github.com/apps/writ-scanner, guide:
|
|
162
|
+
https://docs.withwrit.com/git-hub-app), which runs the scan on every push
|
|
163
|
+
and pull request; the JSON report (`--format json`) carries the same
|
|
164
|
+
pointer under `github_app`.
|
|
165
|
+
|
|
154
166
|
TS/JS is **scan-only**: findings are listed with verbs for your policy file,
|
|
155
167
|
but `writ scan --apply` never rewrites TS/JS files — gate those by hand.
|
|
156
168
|
Covered patterns: `fetch`/`axios` writes, `fs` writes, SQL through knex-style
|
|
@@ -183,16 +195,17 @@ example workflow: [examples/github-action/writ-scan.yml](examples/github-action/
|
|
|
183
195
|
|
|
184
196
|
## GitHub App
|
|
185
197
|
|
|
186
|
-
Install the [Writ GitHub App](https://
|
|
198
|
+
Install the [Writ GitHub App](https://github.com/apps/writ-scanner) on selected
|
|
187
199
|
repositories: every push and pull request is scanned for ungated write-sites,
|
|
188
200
|
with results as a check run on the PR and in the
|
|
189
201
|
[portal](https://app.withwrit.com), where you manage policy, keys, and the audit log.
|
|
202
|
+
Setup and data handling: [GitHub App docs](https://docs.withwrit.com/git-hub-app).
|
|
190
203
|
|
|
191
204
|
## MCP server (`writ-mcp`)
|
|
192
205
|
|
|
193
206
|
Give any MCP-compatible agent point-of-action policy checks. `writ-mcp` is a
|
|
194
207
|
[Model Context Protocol](https://modelcontextprotocol.io) server (stdio transport,
|
|
195
|
-
built on the MCP Python SDK) that exposes the Writ gate as **
|
|
208
|
+
built on the MCP Python SDK) that exposes the Writ gate as **17 MCP tools**:
|
|
196
209
|
the agent calls `writ_check` before a consequential write and gets back `ALLOW`,
|
|
197
210
|
`DENY`, or `STEP_UP` — with a tamper-evident, hash-chained audit receipt for
|
|
198
211
|
every decision.
|
|
@@ -212,13 +225,21 @@ pip install writ-mcp # then run `writ-mcp`
|
|
|
212
225
|
| `writ_receipts` | Read the tenant's audit log |
|
|
213
226
|
| `writ_policy` | Manage the verb policy |
|
|
214
227
|
| `writ_sandbox` | Keyless 90-second demo grant — no API key needed |
|
|
228
|
+
| `writ_github_installations` | List connected GitHub App installations |
|
|
229
|
+
| `writ_github_set_threshold` | Set the check-run fail threshold per install |
|
|
230
|
+
| `writ_github_toggle_pr_comments` | Enable/disable the PR-comment bot |
|
|
231
|
+
| `writ_manifests` | List repos with risk profiles or fetch one manifest |
|
|
232
|
+
| `writ_explain_receipt` | Explain a receipt in plain language |
|
|
233
|
+
| `writ_tenant_notify` | Get or update step-up notification settings |
|
|
234
|
+
| `writ_principals` | List the tenant's principals |
|
|
235
|
+
| `writ_verbs` | List the tenant's verb vocabulary |
|
|
236
|
+
| `writ_keys` | List API key metadata |
|
|
215
237
|
|
|
216
238
|
The gate tools need a free Writ API key (`WRIT_API_KEY`): 10,000 receipts/month
|
|
217
239
|
free, no credit card. `writ_sandbox` works with no key at all.
|
|
218
240
|
|
|
219
241
|
The server implementation lives in [`mcp/`](mcp/) (MIT). Also published on the
|
|
220
|
-
official MCP Registry as `io.github.withwrit/writ
|
|
221
|
-
[Smithery](https://smithery.ai/server/withwrit/writ-mcp), and listed on
|
|
242
|
+
official MCP Registry as `io.github.withwrit/writ` and listed on
|
|
222
243
|
[Glama](https://glama.ai/mcp/servers/withwrit/pywrit).
|
|
223
244
|
|
|
224
245
|
## Python client
|
|
@@ -129,6 +129,18 @@ 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
|
+
|
|
138
|
+
Every scan report ends with a one-line pointer to the Writ GitHub App
|
|
139
|
+
(install: https://github.com/apps/writ-scanner, guide:
|
|
140
|
+
https://docs.withwrit.com/git-hub-app), which runs the scan on every push
|
|
141
|
+
and pull request; the JSON report (`--format json`) carries the same
|
|
142
|
+
pointer under `github_app`.
|
|
143
|
+
|
|
132
144
|
TS/JS is **scan-only**: findings are listed with verbs for your policy file,
|
|
133
145
|
but `writ scan --apply` never rewrites TS/JS files — gate those by hand.
|
|
134
146
|
Covered patterns: `fetch`/`axios` writes, `fs` writes, SQL through knex-style
|
|
@@ -161,16 +173,17 @@ example workflow: [examples/github-action/writ-scan.yml](examples/github-action/
|
|
|
161
173
|
|
|
162
174
|
## GitHub App
|
|
163
175
|
|
|
164
|
-
Install the [Writ GitHub App](https://
|
|
176
|
+
Install the [Writ GitHub App](https://github.com/apps/writ-scanner) on selected
|
|
165
177
|
repositories: every push and pull request is scanned for ungated write-sites,
|
|
166
178
|
with results as a check run on the PR and in the
|
|
167
179
|
[portal](https://app.withwrit.com), where you manage policy, keys, and the audit log.
|
|
180
|
+
Setup and data handling: [GitHub App docs](https://docs.withwrit.com/git-hub-app).
|
|
168
181
|
|
|
169
182
|
## MCP server (`writ-mcp`)
|
|
170
183
|
|
|
171
184
|
Give any MCP-compatible agent point-of-action policy checks. `writ-mcp` is a
|
|
172
185
|
[Model Context Protocol](https://modelcontextprotocol.io) server (stdio transport,
|
|
173
|
-
built on the MCP Python SDK) that exposes the Writ gate as **
|
|
186
|
+
built on the MCP Python SDK) that exposes the Writ gate as **17 MCP tools**:
|
|
174
187
|
the agent calls `writ_check` before a consequential write and gets back `ALLOW`,
|
|
175
188
|
`DENY`, or `STEP_UP` — with a tamper-evident, hash-chained audit receipt for
|
|
176
189
|
every decision.
|
|
@@ -190,13 +203,21 @@ pip install writ-mcp # then run `writ-mcp`
|
|
|
190
203
|
| `writ_receipts` | Read the tenant's audit log |
|
|
191
204
|
| `writ_policy` | Manage the verb policy |
|
|
192
205
|
| `writ_sandbox` | Keyless 90-second demo grant — no API key needed |
|
|
206
|
+
| `writ_github_installations` | List connected GitHub App installations |
|
|
207
|
+
| `writ_github_set_threshold` | Set the check-run fail threshold per install |
|
|
208
|
+
| `writ_github_toggle_pr_comments` | Enable/disable the PR-comment bot |
|
|
209
|
+
| `writ_manifests` | List repos with risk profiles or fetch one manifest |
|
|
210
|
+
| `writ_explain_receipt` | Explain a receipt in plain language |
|
|
211
|
+
| `writ_tenant_notify` | Get or update step-up notification settings |
|
|
212
|
+
| `writ_principals` | List the tenant's principals |
|
|
213
|
+
| `writ_verbs` | List the tenant's verb vocabulary |
|
|
214
|
+
| `writ_keys` | List API key metadata |
|
|
193
215
|
|
|
194
216
|
The gate tools need a free Writ API key (`WRIT_API_KEY`): 10,000 receipts/month
|
|
195
217
|
free, no credit card. `writ_sandbox` works with no key at all.
|
|
196
218
|
|
|
197
219
|
The server implementation lives in [`mcp/`](mcp/) (MIT). Also published on the
|
|
198
|
-
official MCP Registry as `io.github.withwrit/writ
|
|
199
|
-
[Smithery](https://smithery.ai/server/withwrit/writ-mcp), and listed on
|
|
220
|
+
official MCP Registry as `io.github.withwrit/writ` and listed on
|
|
200
221
|
[Glama](https://glama.ai/mcp/servers/withwrit/pywrit).
|
|
201
222
|
|
|
202
223
|
## Python client
|
|
@@ -591,6 +591,19 @@ _SCORE_GAPS = [
|
|
|
591
591
|
"indirect writes through shared HTTP clients several layers down",
|
|
592
592
|
]
|
|
593
593
|
|
|
594
|
+
# Every scan report closes with a pointer at the GitHub App: the local scan
|
|
595
|
+
# is invisible by design, the app is the visible surface (a scan on every
|
|
596
|
+
# push and pull request, check runs, history in the portal). The same
|
|
597
|
+
# pointer rides the JSON report under `github_app` for machine consumers.
|
|
598
|
+
# Text and JSON share these constants so they cannot drift.
|
|
599
|
+
_GITHUB_APP_INSTALL_URL = "https://github.com/apps/writ-scanner"
|
|
600
|
+
_GITHUB_APP_DOCS_URL = "https://docs.withwrit.com/git-hub-app"
|
|
601
|
+
_GITHUB_APP_NOTE = ("Run this scan on every push and pull request with the "
|
|
602
|
+
"Writ GitHub App: check runs on each change, history in "
|
|
603
|
+
"the portal.")
|
|
604
|
+
_GITHUB_APP_LINE = "%s Install: %s (guide: %s)" % (
|
|
605
|
+
_GITHUB_APP_NOTE, _GITHUB_APP_INSTALL_URL, _GITHUB_APP_DOCS_URL)
|
|
606
|
+
|
|
594
607
|
|
|
595
608
|
def _risk_tier(verb):
|
|
596
609
|
"""Classify an inferred verb (domain.action) into high/medium/low risk.
|
|
@@ -826,6 +839,54 @@ _TSJS_EXTS = {".ts": "typescript", ".tsx": "tsx", ".js": "javascript",
|
|
|
826
839
|
_TSJS_SKIP_DIR_NAMES = _SKIP_DIR_NAMES | {".next", "vendor", "venv", ".venv"}
|
|
827
840
|
_TSJS_TEST_DIRS = {"tests", "testing", "__tests__"}
|
|
828
841
|
_TSJS_MAX_BYTES = 1000000 # larger files are almost always bundles
|
|
842
|
+
|
|
843
|
+
# Non-product path classes. Write findings from these paths parse as real
|
|
844
|
+
# writes but are almost never product behavior — docs tooling, build/test
|
|
845
|
+
# scripts, demos, benchmarks (the axios-class scan noise: gulpfile.js,
|
|
846
|
+
# docs/scripts/*, sandbox/*, scripts/benchmark-*). They are suppressed from
|
|
847
|
+
# the report by default — counted per class under "suppressed" — and
|
|
848
|
+
# restored with --include-non-product. Matching is by whole directory
|
|
849
|
+
# segment or exact build-file basename, never filename substring, so
|
|
850
|
+
# product code next to an excluded directory (and files like
|
|
851
|
+
# lib/benchmark-utils.ts) stays reported. This is the single, central
|
|
852
|
+
# exclusion list for TS/JS; don't scatter string matches elsewhere.
|
|
853
|
+
_TSJS_NON_PRODUCT_DIRS = {
|
|
854
|
+
"docs": {"docs", "doc"},
|
|
855
|
+
"scripts": {"scripts"},
|
|
856
|
+
"examples": {"examples", "example"},
|
|
857
|
+
"sandbox": {"sandbox"},
|
|
858
|
+
"benchmark": {"benchmark", "benchmarks"},
|
|
859
|
+
"demo": {"demo", "demos"},
|
|
860
|
+
}
|
|
861
|
+
_TSJS_BUILD_TOOL_FILE = _re.compile(
|
|
862
|
+
r"^(gulpfile|gruntfile)(\.babel)?\.(js|mjs|cjs|ts)$"
|
|
863
|
+
r"|^(webpack|rollup|vite|esbuild|tsup|snowpack|babel)\.config\.(js|mjs|cjs|ts)$"
|
|
864
|
+
r"|^karma\.conf\.(js|mjs|cjs|ts)$", _re.I)
|
|
865
|
+
|
|
866
|
+
|
|
867
|
+
def _tsjs_non_product_class(path, root):
|
|
868
|
+
"""Return the non-product path class for a TS/JS file, or None.
|
|
869
|
+
|
|
870
|
+
Directory classes match on whole path segments (docs/, scripts/,
|
|
871
|
+
sandbox/, examples/, benchmark/, demo/ at any depth), so a product
|
|
872
|
+
file beside an excluded directory is unaffected. Build-tooling files
|
|
873
|
+
(gulpfile.js, Gruntfile.js, webpack.config.*, rollup.config.*,
|
|
874
|
+
vite.config.*, and equivalents) match by exact basename anywhere in
|
|
875
|
+
the tree so monorepo package configs are covered too.
|
|
876
|
+
"""
|
|
877
|
+
rel = path.relative_to(root)
|
|
878
|
+
segs = set(rel.parts[:-1])
|
|
879
|
+
for cls, names in _TSJS_NON_PRODUCT_DIRS.items():
|
|
880
|
+
if segs & names:
|
|
881
|
+
return cls
|
|
882
|
+
if _TSJS_BUILD_TOOL_FILE.match(path.name):
|
|
883
|
+
return "build-tooling"
|
|
884
|
+
return None
|
|
885
|
+
|
|
886
|
+
|
|
887
|
+
def _tsjs_suppressed_total(suppressed):
|
|
888
|
+
"""Total suppressed sites across all non-product classes."""
|
|
889
|
+
return sum(b["sites"] for b in (suppressed or {}).values())
|
|
829
890
|
_TSJS_HINT = ("hint: %d TS/JS file(s) not scanned; install the extra: "
|
|
830
891
|
"pip install 'pywrit[polyglot]'")
|
|
831
892
|
_TSJS_WRITE_METHODS = {"post", "put", "patch", "delete"}
|
|
@@ -1289,12 +1350,17 @@ def _tsjs_verb(rel, func_name, cls_name, kind):
|
|
|
1289
1350
|
return infer_verb(base, snake, cls_name, kind)
|
|
1290
1351
|
|
|
1291
1352
|
|
|
1292
|
-
def _tsjs_scan(root, excludes):
|
|
1293
|
-
"""Return dict with files, skipped, sites, gated, or hint
|
|
1294
|
-
extra is missing. Never raises on a bad file.
|
|
1353
|
+
def _tsjs_scan(root, excludes, include_non_product=False):
|
|
1354
|
+
"""Return dict with files, skipped, sites, gated, suppressed, or hint
|
|
1355
|
+
when the extra is missing. Never raises on a bad file.
|
|
1356
|
+
|
|
1357
|
+
Findings from non-product paths (_tsjs_non_product_class) are not
|
|
1358
|
+
dropped — they are counted per path class in res["suppressed"] so the
|
|
1359
|
+
report can say exactly what was held back. include_non_product restores
|
|
1360
|
+
the old behavior of reporting every site."""
|
|
1295
1361
|
files = _tsjs_collect_files(root, excludes)
|
|
1296
1362
|
res = {"files": files, "skipped": [], "sites": [], "gated": set(),
|
|
1297
|
-
"missing_extra": False}
|
|
1363
|
+
"suppressed": {}, "missing_extra": False}
|
|
1298
1364
|
if not files:
|
|
1299
1365
|
return res
|
|
1300
1366
|
parsers = _tsjs_parsers()
|
|
@@ -1312,6 +1378,14 @@ def _tsjs_scan(root, excludes):
|
|
|
1312
1378
|
except Exception:
|
|
1313
1379
|
res["skipped"].append(str(path))
|
|
1314
1380
|
continue
|
|
1381
|
+
cls = None if include_non_product \
|
|
1382
|
+
else _tsjs_non_product_class(path, root)
|
|
1383
|
+
if cls is not None and sites:
|
|
1384
|
+
bucket = res["suppressed"].setdefault(
|
|
1385
|
+
cls, {"sites": 0, "files": {}})
|
|
1386
|
+
bucket["sites"] += len(sites)
|
|
1387
|
+
bucket["files"][str(path)] = len(sites)
|
|
1388
|
+
continue
|
|
1315
1389
|
res["sites"].extend(sites)
|
|
1316
1390
|
res["gated"].update((str(path),) + g for g in gated)
|
|
1317
1391
|
return res
|
|
@@ -1372,13 +1446,32 @@ def print_scan_json(root, files, skipped, sites, gated_funcs, tsjs, ts_sites):
|
|
|
1372
1446
|
"files_scanned": len(files) + len(tsjs.get("files", [])),
|
|
1373
1447
|
"files_skipped": len(skipped) + len(tsjs.get("skipped", [])),
|
|
1374
1448
|
"tsjs_hint": bool(tsjs.get("missing_extra")),
|
|
1449
|
+
"github_app": {
|
|
1450
|
+
"install_url": _GITHUB_APP_INSTALL_URL,
|
|
1451
|
+
"docs_url": _GITHUB_APP_DOCS_URL,
|
|
1452
|
+
"note": _GITHUB_APP_NOTE,
|
|
1453
|
+
},
|
|
1375
1454
|
"findings": _scan_findings_json(root, sites, gated_funcs, tsjs,
|
|
1376
1455
|
ts_sites),
|
|
1377
1456
|
}
|
|
1457
|
+
ts_suppressed = tsjs.get("suppressed") or {}
|
|
1458
|
+
ts_sup_total = _tsjs_suppressed_total(ts_suppressed)
|
|
1459
|
+
if ts_sup_total:
|
|
1460
|
+
# Non-product findings held back by default: never dropped
|
|
1461
|
+
# silently — the report names every suppressed path.
|
|
1462
|
+
doc["tsjs_suppressed_non_product"] = {
|
|
1463
|
+
"sites": ts_sup_total,
|
|
1464
|
+
"by_class": {c: ts_suppressed[c]["sites"]
|
|
1465
|
+
for c in sorted(ts_suppressed)},
|
|
1466
|
+
"files": sorted(
|
|
1467
|
+
str(_pathlib.Path(f).relative_to(root))
|
|
1468
|
+
for c in ts_suppressed.values()
|
|
1469
|
+
for f in c["files"]),
|
|
1470
|
+
}
|
|
1378
1471
|
print(json.dumps(doc, indent=2))
|
|
1379
1472
|
|
|
1380
1473
|
|
|
1381
|
-
def _scan_repo(root, excludes):
|
|
1474
|
+
def _scan_repo(root, excludes, include_non_product=False):
|
|
1382
1475
|
"""Collect Python and TS/JS files and find write sites.
|
|
1383
1476
|
|
|
1384
1477
|
Returns (files, skipped, sites, gated, tsjs). This is the read-only
|
|
@@ -1402,7 +1495,8 @@ def _scan_repo(root, excludes):
|
|
|
1402
1495
|
sites.extend(v.sites)
|
|
1403
1496
|
gated.update((str(path), n, ln) for (n, ln) in v.gated)
|
|
1404
1497
|
|
|
1405
|
-
tsjs = _tsjs_scan(root, excludes or []
|
|
1498
|
+
tsjs = _tsjs_scan(root, excludes or [],
|
|
1499
|
+
include_non_product=include_non_product)
|
|
1406
1500
|
return files, skipped, sites, gated, tsjs
|
|
1407
1501
|
|
|
1408
1502
|
|
|
@@ -1516,7 +1610,9 @@ def scan_cmd(args):
|
|
|
1516
1610
|
print("error: not a directory: %s" % args.path, file=sys.stderr)
|
|
1517
1611
|
return 2
|
|
1518
1612
|
|
|
1519
|
-
files, skipped, sites, gated, tsjs = _scan_repo(
|
|
1613
|
+
files, skipped, sites, gated, tsjs = _scan_repo(
|
|
1614
|
+
root, args.exclude or [],
|
|
1615
|
+
include_non_product=getattr(args, "include_non_product", False))
|
|
1520
1616
|
analysis = _analyze_scan(root, files, skipped, sites, gated, tsjs)
|
|
1521
1617
|
by_func = analysis["by_func"]
|
|
1522
1618
|
ts_by_func = analysis["ts_by_func"]
|
|
@@ -1538,6 +1634,7 @@ def scan_cmd(args):
|
|
|
1538
1634
|
|
|
1539
1635
|
if args.score:
|
|
1540
1636
|
print_score_report(root, sites, gated_funcs)
|
|
1637
|
+
print(_GITHUB_APP_LINE)
|
|
1541
1638
|
return 0
|
|
1542
1639
|
|
|
1543
1640
|
print("writ scan: %s" % root)
|
|
@@ -1560,6 +1657,19 @@ def scan_cmd(args):
|
|
|
1560
1657
|
print(" %s:%d [%s] %s %s(): %s" % (
|
|
1561
1658
|
_pathlib.Path(s.file).relative_to(root), s.lineno, s.kind,
|
|
1562
1659
|
rid, s.func or "<module>", s.snippet))
|
|
1660
|
+
suppressed = tsjs.get("suppressed") or {}
|
|
1661
|
+
sup_total = _tsjs_suppressed_total(suppressed)
|
|
1662
|
+
if sup_total:
|
|
1663
|
+
by_class = ", ".join("%s: %d" % (c, suppressed[c]["sites"])
|
|
1664
|
+
for c in sorted(suppressed))
|
|
1665
|
+
print(" ts/js non-product: %d site(s) suppressed (%s); "
|
|
1666
|
+
"re-run with --include-non-product to show them"
|
|
1667
|
+
% (sup_total, by_class))
|
|
1668
|
+
for cls in sorted(suppressed):
|
|
1669
|
+
for f in sorted(suppressed[cls]["files"]):
|
|
1670
|
+
print(" suppressed %s: %d site(s) [%s]" % (
|
|
1671
|
+
_pathlib.Path(f).relative_to(root),
|
|
1672
|
+
suppressed[cls]["files"][f], cls))
|
|
1563
1673
|
if verbs:
|
|
1564
1674
|
print(" verbs discovered: %d" % len(verbs))
|
|
1565
1675
|
for vname in sorted(verbs):
|
|
@@ -1584,6 +1694,7 @@ def scan_cmd(args):
|
|
|
1584
1694
|
"gate them by hand).")
|
|
1585
1695
|
else:
|
|
1586
1696
|
print("nothing to instrument.")
|
|
1697
|
+
print(_GITHUB_APP_LINE)
|
|
1587
1698
|
return 0
|
|
1588
1699
|
|
|
1589
1700
|
do_apply = args.apply
|
|
@@ -1605,7 +1716,10 @@ def scan_cmd(args):
|
|
|
1605
1716
|
if not args.key:
|
|
1606
1717
|
print("error: --push-policy needs --key", file=sys.stderr)
|
|
1607
1718
|
return 2
|
|
1608
|
-
|
|
1719
|
+
code = request("PUT", "/v1/policy", verbs, key=args.key)
|
|
1720
|
+
print(_GITHUB_APP_LINE)
|
|
1721
|
+
return code
|
|
1722
|
+
print(_GITHUB_APP_LINE)
|
|
1609
1723
|
return 0
|
|
1610
1724
|
|
|
1611
1725
|
|
|
@@ -2138,6 +2252,13 @@ def main():
|
|
|
2138
2252
|
help="Output format: human-readable text (default) or "
|
|
2139
2253
|
"machine-readable JSON risk report (read-only; no "
|
|
2140
2254
|
"policy file, no diffs)")
|
|
2255
|
+
scan.add_argument("--include-non-product", action="store_true",
|
|
2256
|
+
help="Include TS/JS findings from non-product paths that the "
|
|
2257
|
+
"scan suppresses by default: docs/, scripts/, sandbox/, "
|
|
2258
|
+
"examples/, benchmark/, demo/ directories and "
|
|
2259
|
+
"build-tooling files (gulpfile.js, webpack.config.*, "
|
|
2260
|
+
"rollup.config.*, vite.config.*, ...). Suppressed sites "
|
|
2261
|
+
"are always reported as a per-class count.")
|
|
2141
2262
|
scan.add_argument("--push-policy", action="store_true",
|
|
2142
2263
|
help="PUT the discovered policy to the gate (needs --key)")
|
|
2143
2264
|
scan.add_argument("--key", default="",
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: pywrit
|
|
3
|
-
Version: 0.2.
|
|
3
|
+
Version: 0.2.11
|
|
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,6 +151,18 @@ 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
|
+
|
|
160
|
+
Every scan report ends with a one-line pointer to the Writ GitHub App
|
|
161
|
+
(install: https://github.com/apps/writ-scanner, guide:
|
|
162
|
+
https://docs.withwrit.com/git-hub-app), which runs the scan on every push
|
|
163
|
+
and pull request; the JSON report (`--format json`) carries the same
|
|
164
|
+
pointer under `github_app`.
|
|
165
|
+
|
|
154
166
|
TS/JS is **scan-only**: findings are listed with verbs for your policy file,
|
|
155
167
|
but `writ scan --apply` never rewrites TS/JS files — gate those by hand.
|
|
156
168
|
Covered patterns: `fetch`/`axios` writes, `fs` writes, SQL through knex-style
|
|
@@ -183,16 +195,17 @@ example workflow: [examples/github-action/writ-scan.yml](examples/github-action/
|
|
|
183
195
|
|
|
184
196
|
## GitHub App
|
|
185
197
|
|
|
186
|
-
Install the [Writ GitHub App](https://
|
|
198
|
+
Install the [Writ GitHub App](https://github.com/apps/writ-scanner) on selected
|
|
187
199
|
repositories: every push and pull request is scanned for ungated write-sites,
|
|
188
200
|
with results as a check run on the PR and in the
|
|
189
201
|
[portal](https://app.withwrit.com), where you manage policy, keys, and the audit log.
|
|
202
|
+
Setup and data handling: [GitHub App docs](https://docs.withwrit.com/git-hub-app).
|
|
190
203
|
|
|
191
204
|
## MCP server (`writ-mcp`)
|
|
192
205
|
|
|
193
206
|
Give any MCP-compatible agent point-of-action policy checks. `writ-mcp` is a
|
|
194
207
|
[Model Context Protocol](https://modelcontextprotocol.io) server (stdio transport,
|
|
195
|
-
built on the MCP Python SDK) that exposes the Writ gate as **
|
|
208
|
+
built on the MCP Python SDK) that exposes the Writ gate as **17 MCP tools**:
|
|
196
209
|
the agent calls `writ_check` before a consequential write and gets back `ALLOW`,
|
|
197
210
|
`DENY`, or `STEP_UP` — with a tamper-evident, hash-chained audit receipt for
|
|
198
211
|
every decision.
|
|
@@ -212,13 +225,21 @@ pip install writ-mcp # then run `writ-mcp`
|
|
|
212
225
|
| `writ_receipts` | Read the tenant's audit log |
|
|
213
226
|
| `writ_policy` | Manage the verb policy |
|
|
214
227
|
| `writ_sandbox` | Keyless 90-second demo grant — no API key needed |
|
|
228
|
+
| `writ_github_installations` | List connected GitHub App installations |
|
|
229
|
+
| `writ_github_set_threshold` | Set the check-run fail threshold per install |
|
|
230
|
+
| `writ_github_toggle_pr_comments` | Enable/disable the PR-comment bot |
|
|
231
|
+
| `writ_manifests` | List repos with risk profiles or fetch one manifest |
|
|
232
|
+
| `writ_explain_receipt` | Explain a receipt in plain language |
|
|
233
|
+
| `writ_tenant_notify` | Get or update step-up notification settings |
|
|
234
|
+
| `writ_principals` | List the tenant's principals |
|
|
235
|
+
| `writ_verbs` | List the tenant's verb vocabulary |
|
|
236
|
+
| `writ_keys` | List API key metadata |
|
|
215
237
|
|
|
216
238
|
The gate tools need a free Writ API key (`WRIT_API_KEY`): 10,000 receipts/month
|
|
217
239
|
free, no credit card. `writ_sandbox` works with no key at all.
|
|
218
240
|
|
|
219
241
|
The server implementation lives in [`mcp/`](mcp/) (MIT). Also published on the
|
|
220
|
-
official MCP Registry as `io.github.withwrit/writ
|
|
221
|
-
[Smithery](https://smithery.ai/server/withwrit/writ-mcp), and listed on
|
|
242
|
+
official MCP Registry as `io.github.withwrit/writ` and listed on
|
|
222
243
|
[Glama](https://glama.ai/mcp/servers/withwrit/pywrit).
|
|
223
244
|
|
|
224
245
|
## Python client
|
|
@@ -337,6 +337,144 @@ class MissingExtraTest(unittest.TestCase):
|
|
|
337
337
|
" orders.create\n" % root.resolve()), out)
|
|
338
338
|
|
|
339
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
|
+
|
|
383
|
+
class GitHubAppLineTest(unittest.TestCase):
|
|
384
|
+
"""Regression: every scan report ends with the GitHub App line.
|
|
385
|
+
|
|
386
|
+
The local scan is invisible by design; the GitHub App is the visible
|
|
387
|
+
surface. The text report's last line points at it on every outcome
|
|
388
|
+
(findings found, zero findings, suppressed-only, --score), and the
|
|
389
|
+
JSON report carries the same pointer under `github_app`.
|
|
390
|
+
"""
|
|
391
|
+
|
|
392
|
+
LINE = ("Run this scan on every push and pull request with the Writ "
|
|
393
|
+
"GitHub App: check runs on each change, history in the portal. "
|
|
394
|
+
"Install: https://github.com/apps/writ-scanner "
|
|
395
|
+
"(guide: https://docs.withwrit.com/git-hub-app)")
|
|
396
|
+
|
|
397
|
+
FINDING_REPO = {
|
|
398
|
+
"app.py": ('import requests\n\n\n'
|
|
399
|
+
'def send(url):\n'
|
|
400
|
+
' return requests.post(url, json={})\n'),
|
|
401
|
+
}
|
|
402
|
+
CLEAN_REPO = {
|
|
403
|
+
"app.py": ('def read():\n'
|
|
404
|
+
' return open("/tmp/x").read()\n'),
|
|
405
|
+
}
|
|
406
|
+
|
|
407
|
+
def _repo(self, root, files):
|
|
408
|
+
for rel, src in files.items():
|
|
409
|
+
p = root / rel
|
|
410
|
+
p.parent.mkdir(parents=True, exist_ok=True)
|
|
411
|
+
p.write_text(src)
|
|
412
|
+
|
|
413
|
+
def _last_line(self, out):
|
|
414
|
+
lines = [ln for ln in out.splitlines() if ln.strip()]
|
|
415
|
+
return lines[-1] if lines else ""
|
|
416
|
+
|
|
417
|
+
def test_findings_found_run_ends_with_app_line(self):
|
|
418
|
+
with tempfile.TemporaryDirectory() as td:
|
|
419
|
+
root = pathlib.Path(td) / "repo"
|
|
420
|
+
root.mkdir()
|
|
421
|
+
self._repo(root, self.FINDING_REPO)
|
|
422
|
+
code, out = _run_scan(root)
|
|
423
|
+
self.assertEqual(code, 0)
|
|
424
|
+
self.assertIn("write sites: 1 in 1 function(s)", out)
|
|
425
|
+
self.assertEqual(self._last_line(out), self.LINE)
|
|
426
|
+
|
|
427
|
+
def test_zero_findings_run_ends_with_app_line(self):
|
|
428
|
+
with tempfile.TemporaryDirectory() as td:
|
|
429
|
+
root = pathlib.Path(td) / "repo"
|
|
430
|
+
root.mkdir()
|
|
431
|
+
self._repo(root, self.CLEAN_REPO)
|
|
432
|
+
code, out = _run_scan(root)
|
|
433
|
+
self.assertEqual(code, 0)
|
|
434
|
+
self.assertIn("write sites: 0 in 0 function(s)", out)
|
|
435
|
+
self.assertEqual(self._last_line(out), self.LINE)
|
|
436
|
+
|
|
437
|
+
def test_score_only_run_ends_with_app_line(self):
|
|
438
|
+
with tempfile.TemporaryDirectory() as td:
|
|
439
|
+
root = pathlib.Path(td) / "repo"
|
|
440
|
+
root.mkdir()
|
|
441
|
+
self._repo(root, self.FINDING_REPO)
|
|
442
|
+
code, out = _run_scan(root, score=True)
|
|
443
|
+
self.assertEqual(code, 0)
|
|
444
|
+
self.assertEqual(self._last_line(out), self.LINE)
|
|
445
|
+
|
|
446
|
+
def test_json_report_carries_github_app_field(self):
|
|
447
|
+
import json as j
|
|
448
|
+
with tempfile.TemporaryDirectory() as td:
|
|
449
|
+
root = pathlib.Path(td) / "repo"
|
|
450
|
+
root.mkdir()
|
|
451
|
+
self._repo(root, self.FINDING_REPO)
|
|
452
|
+
code, out = _run_scan(root, format="json")
|
|
453
|
+
self.assertEqual(code, 0, out)
|
|
454
|
+
app = j.loads(out)["github_app"]
|
|
455
|
+
self.assertEqual(app, {
|
|
456
|
+
"install_url": "https://github.com/apps/writ-scanner",
|
|
457
|
+
"docs_url": "https://docs.withwrit.com/git-hub-app",
|
|
458
|
+
"note": ("Run this scan on every push and pull request with "
|
|
459
|
+
"the Writ GitHub App: check runs on each change, "
|
|
460
|
+
"history in the portal."),
|
|
461
|
+
})
|
|
462
|
+
|
|
463
|
+
@unittest.skipUnless(HAVE_EXTRA, "polyglot extra not installed")
|
|
464
|
+
def test_suppressed_only_run_ends_with_app_line(self):
|
|
465
|
+
with tempfile.TemporaryDirectory() as td:
|
|
466
|
+
root = pathlib.Path(td) / "repo"
|
|
467
|
+
root.mkdir()
|
|
468
|
+
self._repo(root, {
|
|
469
|
+
"docs/scripts/tool.js": NonProductScanTest.WRITE * 3,
|
|
470
|
+
})
|
|
471
|
+
code, out = _run_scan(root)
|
|
472
|
+
self.assertEqual(code, 0)
|
|
473
|
+
self.assertIn("ts/js write sites: 0 in 0 function(s)", out)
|
|
474
|
+
self.assertIn("ts/js non-product: 3 site(s) suppressed", out)
|
|
475
|
+
self.assertEqual(self._last_line(out), self.LINE)
|
|
476
|
+
|
|
477
|
+
|
|
340
478
|
class CliSyncTest(unittest.TestCase):
|
|
341
479
|
def test_download_copy_is_byte_identical(self):
|
|
342
480
|
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
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|