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.
- {pywrit-0.2.8/src/pywrit.egg-info → pywrit-0.2.10}/PKG-INFO +31 -5
- {pywrit-0.2.8 → pywrit-0.2.10}/README.md +30 -4
- {pywrit-0.2.8 → pywrit-0.2.10}/pyproject.toml +1 -1
- {pywrit-0.2.8 → pywrit-0.2.10}/src/pywrit/__init__.py +1 -1
- {pywrit-0.2.8 → pywrit-0.2.10}/src/pywrit/cli.py +152 -10
- {pywrit-0.2.8 → pywrit-0.2.10/src/pywrit.egg-info}/PKG-INFO +31 -5
- {pywrit-0.2.8 → pywrit-0.2.10}/tests/test_scan_tsjs.py +109 -3
- {pywrit-0.2.8 → pywrit-0.2.10}/LICENSE +0 -0
- {pywrit-0.2.8 → pywrit-0.2.10}/setup.cfg +0 -0
- {pywrit-0.2.8 → pywrit-0.2.10}/src/pywrit/client.py +0 -0
- {pywrit-0.2.8 → pywrit-0.2.10}/src/pywrit/errors.py +0 -0
- {pywrit-0.2.8 → pywrit-0.2.10}/src/pywrit.egg-info/SOURCES.txt +0 -0
- {pywrit-0.2.8 → pywrit-0.2.10}/src/pywrit.egg-info/dependency_links.txt +0 -0
- {pywrit-0.2.8 → pywrit-0.2.10}/src/pywrit.egg-info/entry_points.txt +0 -0
- {pywrit-0.2.8 → pywrit-0.2.10}/src/pywrit.egg-info/requires.txt +0 -0
- {pywrit-0.2.8 → pywrit-0.2.10}/src/pywrit.egg-info/top_level.txt +0 -0
- {pywrit-0.2.8 → pywrit-0.2.10}/tests/test_client.py +0 -0
- {pywrit-0.2.8 → pywrit-0.2.10}/tests/test_scan_json.py +0 -0
- {pywrit-0.2.8 → pywrit-0.2.10}/tests/test_scan_python.py +0 -0
- {pywrit-0.2.8 → pywrit-0.2.10}/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.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,
|
|
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 **
|
|
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
|
|
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,
|
|
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 **
|
|
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
|
|
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
|
|
@@ -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
|
-
|
|
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
|
|
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(
|
|
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.
|
|
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,
|
|
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 **
|
|
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
|
|
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:
|
|
117
|
-
self.assertIn("ts/js write sites: %d in
|
|
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
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|