midnight-shield 0.0.0-stage → 0.4.0
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.
- package/CHANGELOG.md +60 -0
- package/LICENSE +21 -0
- package/README.md +384 -2
- package/action.yml +56 -0
- package/dist/src/analyzer.d.ts +97 -0
- package/dist/src/analyzer.js +895 -0
- package/dist/src/ast.d.ts +211 -0
- package/dist/src/ast.js +2 -0
- package/dist/src/browser.d.ts +3 -0
- package/dist/src/browser.js +5 -0
- package/dist/src/cli.d.ts +2 -0
- package/dist/src/cli.js +336 -0
- package/dist/src/config.d.ts +26 -0
- package/dist/src/config.js +87 -0
- package/dist/src/fixes.d.ts +10 -0
- package/dist/src/fixes.js +45 -0
- package/dist/src/index.d.ts +10 -0
- package/dist/src/index.js +10 -0
- package/dist/src/lexer.d.ts +18 -0
- package/dist/src/lexer.js +135 -0
- package/dist/src/linter.d.ts +67 -0
- package/dist/src/linter.js +137 -0
- package/dist/src/node.d.ts +13 -0
- package/dist/src/node.js +98 -0
- package/dist/src/parser.d.ts +2 -0
- package/dist/src/parser.js +791 -0
- package/dist/src/plugin-loader.d.ts +3 -0
- package/dist/src/plugin-loader.js +31 -0
- package/dist/src/plugins.d.ts +34 -0
- package/dist/src/plugins.js +59 -0
- package/dist/src/reporters.d.ts +22 -0
- package/dist/src/reporters.js +286 -0
- package/dist/src/rules.d.ts +23 -0
- package/dist/src/rules.js +104 -0
- package/dist/src/sdk.d.ts +6 -0
- package/dist/src/sdk.js +130 -0
- package/dist/src/walk.d.ts +28 -0
- package/dist/src/walk.js +110 -0
- package/docs/rules/MS000.md +7 -0
- package/docs/rules/MS001.md +46 -0
- package/docs/rules/MS002.md +42 -0
- package/docs/rules/MS003.md +41 -0
- package/docs/rules/MS004.md +41 -0
- package/docs/rules/MS005.md +32 -0
- package/docs/rules/MS006.md +17 -0
- package/docs/rules/MS007.md +44 -0
- package/docs/rules/MS008.md +59 -0
- package/docs/rules/MS009.md +45 -0
- package/docs/rules/MS010.md +46 -0
- package/docs/rules/MS101.md +32 -0
- package/docs/rules/MS102.md +31 -0
- package/package.json +67 -4
- package/skills/midnight-shield/SKILL.md +67 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses [Semantic Versioning](https://semver.org/).
|
|
4
|
+
|
|
5
|
+
## [0.4.0] - 2026-11-20
|
|
6
|
+
|
|
7
|
+
### Added
|
|
8
|
+
|
|
9
|
+
- **Disclosure map** (`--print disclosures`): every point where data becomes public (`disclose()`, ledger writes, exported return values), the private inputs that flow there, and whether they are raw, hashed or committed.
|
|
10
|
+
- **Confidence** for every finding (high, medium, low), separate from severity. `--min-confidence` filters by it. Name-based rules report low confidence.
|
|
11
|
+
- **Baselines**: `--write-baseline` records current findings; `--baseline` reports only new ones. Fingerprints survive code moving to other lines.
|
|
12
|
+
- `--show-suppressed`, and SARIF `suppressions` for findings hidden by comments or a baseline.
|
|
13
|
+
- `--format markdown` report for audits and pull requests.
|
|
14
|
+
- `midnight-shield explain <RULE>`.
|
|
15
|
+
- `--fix` / `--fix-dry-run` for fixes that cannot change contract behavior (MS006).
|
|
16
|
+
- **Custom rules** via plugins (`--plugin`, `"plugins"` in config) with an AST visitor API. See `docs/custom-rules.md`.
|
|
17
|
+
- MS010 `linkable-ledger-update`: in contracts with anonymous Merkle membership, the same secret-derived identifier is published by several circuits.
|
|
18
|
+
- **TypeScript/JavaScript checks**: MS101 `remote-proof-server`, MS102 `secret-in-log`. Test files are skipped. `--no-sdk` turns them off.
|
|
19
|
+
- **Web playground** (`playground/`, published with GitHub Pages): paste a contract and see findings and the disclosure map in the browser.
|
|
20
|
+
- **VS Code extension** (`vscode/`): diagnostics as you type, rule links, workspace scan, disclosure map command.
|
|
21
|
+
- **npm package** ready to publish (`npx midnight-shield`), with a release workflow.
|
|
22
|
+
- Corpus verification now also scans the TypeScript/JavaScript files of both corpora (1,052 files).
|
|
23
|
+
|
|
24
|
+
### Changed
|
|
25
|
+
|
|
26
|
+
- The analysis core no longer depends on Node.js, so it runs in the browser. File-system helpers moved to `node.ts`.
|
|
27
|
+
- `pin` is no longer treated as a secret name (it was mostly version pins).
|
|
28
|
+
|
|
29
|
+
## [0.3.0] - 2026-11-20
|
|
30
|
+
|
|
31
|
+
### Added
|
|
32
|
+
|
|
33
|
+
- MS007 `disclosed-secret`: the raw value of a secret-named witness or parameter is made public.
|
|
34
|
+
- MS008 `missing-nullifier`: Merkle-authorized state change without a nullifier check.
|
|
35
|
+
- MS009 `unbound-merkle-path`: Merkle root checked without tying the path's leaf to the caller.
|
|
36
|
+
- Corpus verification (`npm run verify`): scans midnight-examples and OpenZeppelin Contracts for Compact at pinned commits and compares with a reviewed baseline.
|
|
37
|
+
- CI compiles the example contracts with the real Compact compiler.
|
|
38
|
+
- Test suite split into lexer, parser, rules, reporters, CLI, examples and fuzz tests (89 tests, about 97% line coverage). `npm run coverage` prints a coverage report.
|
|
39
|
+
|
|
40
|
+
### Changed
|
|
41
|
+
|
|
42
|
+
- Circuits are followed up to 8 calls deep (was 4).
|
|
43
|
+
|
|
44
|
+
## [0.2.0] - 2026-11-20
|
|
45
|
+
|
|
46
|
+
### Added
|
|
47
|
+
|
|
48
|
+
- Follows `import "path" prefix X_;` into other files.
|
|
49
|
+
- Code frames and rule links in text output.
|
|
50
|
+
- `midnight-shield.config.json` (`--init`, `--config`), `--ignore`, `--no-code-frame`.
|
|
51
|
+
- Claude Code skill in `skills/midnight-shield`.
|
|
52
|
+
|
|
53
|
+
## [0.1.0] - 2026-11-20
|
|
54
|
+
|
|
55
|
+
### Added
|
|
56
|
+
|
|
57
|
+
- Compact lexer and parser with error recovery.
|
|
58
|
+
- Data-flow analyzer and rules MS000 to MS006.
|
|
59
|
+
- CLI with text, JSON and SARIF output.
|
|
60
|
+
- GitHub Action with SARIF upload.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 efforthye
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,385 @@
|
|
|
1
|
-
|
|
1
|
+
<div align="center">
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
# 🛡️ Midnight Shield
|
|
4
|
+
|
|
5
|
+
**Static analyzer for Midnight Compact contracts and the TypeScript code around them.**
|
|
6
|
+
Catch security and privacy bugs before you deploy: in your terminal, your editor, your browser, CI, and AI coding agents.
|
|
7
|
+
|
|
8
|
+
[](https://github.com/efforthye/midnight-shield/actions/workflows/ci.yml)
|
|
9
|
+
[](LICENSE)
|
|
10
|
+

|
|
11
|
+

|
|
12
|
+

|
|
13
|
+
-96%25-brightgreen)
|
|
14
|
+
[](https://www.npmjs.com/package/midnight-shield)
|
|
15
|
+
|
|
16
|
+
[Quick start](#quick-start) · [Web playground](#web-playground) · [Rules](#rules) · [Disclosure map](#disclosure-map) · [Editor](#vs-code) · [CI](#github-action) · [AI agents](#use-with-ai-coding-agents) · [Verification](#testing-and-verification)
|
|
17
|
+
|
|
18
|
+
<img src="https://raw.githubusercontent.com/efforthye/midnight-shield/main/docs/assets/demo.png" alt="Midnight Shield scanning a vulnerable Compact contract" width="820">
|
|
19
|
+
|
|
20
|
+
**[▶ Try it in your browser](https://efforthye.github.io/midnight-shield/)** · no install, your code never leaves the page
|
|
21
|
+
|
|
22
|
+
<sub>Community project for the Midnight ecosystem. Not an official Midnight Foundation product.</sub>
|
|
23
|
+
|
|
24
|
+
</div>
|
|
25
|
+
|
|
26
|
+
---
|
|
27
|
+
|
|
28
|
+
## Why Midnight Shield?
|
|
29
|
+
|
|
30
|
+
The Compact compiler already stops you from disclosing witness data by accident. But a contract can **compile cleanly and still leak or be exploitable**:
|
|
31
|
+
|
|
32
|
+
| Bug | What goes wrong | Rule |
|
|
33
|
+
| --- | --- | --- |
|
|
34
|
+
| "Owner" check with `ownPublicKey()` | The prover supplies that value, so anyone can pass the check | [MS001](docs/rules/MS001.md) |
|
|
35
|
+
| Unchecked witness | The user can write any balance, score, or state to the ledger | [MS002](docs/rules/MS002.md) |
|
|
36
|
+
| Public hash of a vote, age, or PIN | Few possible inputs, so the hash can be brute-forced | [MS003](docs/rules/MS003.md) |
|
|
37
|
+
| Commitment with public or reused randomness | The commitment hides nothing, or links users together | [MS004](docs/rules/MS004.md) |
|
|
38
|
+
| `disclose(secretKey())` | The secret key is published for everyone to read | [MS007](docs/rules/MS007.md) |
|
|
39
|
+
| Merkle membership with no nullifier | One member can vote or claim again and again | [MS008](docs/rules/MS008.md) |
|
|
40
|
+
| Merkle root checked, leaf never checked | Anyone can reuse another member's public path | [MS009](docs/rules/MS009.md) |
|
|
41
|
+
| Same member tag in every circuit | Anonymous members' actions can be linked together | [MS010](docs/rules/MS010.md) |
|
|
42
|
+
| Remote proof server in the DApp | A third party sees every user's private inputs | [MS101](docs/rules/MS101.md) |
|
|
43
|
+
| Wallet seed in a log | The seed ends up in CI logs and crash reports | [MS102](docs/rules/MS102.md) |
|
|
44
|
+
|
|
45
|
+
Midnight Shield is to Midnight what **Slither** is to Solidity and **aztec-lint** is to Noir: a static analyzer that catches issues before deploy, with rules built around Midnight's privacy model.
|
|
46
|
+
|
|
47
|
+
## Highlights
|
|
48
|
+
|
|
49
|
+
- 🔍 **Real parser and data-flow analysis.** Tracks every value back to witnesses, private inputs, public ledger state, or constants, across helper circuits and imported files.
|
|
50
|
+
- 🗺️ **Disclosure map.** One table of everything your contract makes public, and whether it is raw, hashed or committed. Unique to Midnight.
|
|
51
|
+
- 🎲 **Entropy-aware.** Knows a `Boolean` vote has 1 bit of secret entropy and a `Bytes<32>` key has 256, so it flags brute-forceable hashes without crying wolf.
|
|
52
|
+
- 🎯 **Honest about certainty.** Every finding has a severity *and* a confidence. Rules that rely on names or guess intent say so.
|
|
53
|
+
- 🧪 **Verified on real code, in CI.** 1,052 files of the official examples and OpenZeppelin Contracts for Compact (Compact and TypeScript) at pinned commits: zero parse errors, zero medium-or-worse findings. Examples are compiled with the real Compact compiler.
|
|
54
|
+
- 🧰 **Everywhere you work.** CLI, web playground, VS Code, GitHub Action with SARIF, Markdown reports, Claude Code skill, plugin API.
|
|
55
|
+
- 🏗️ **Easy to adopt.** Baselines accept existing findings so CI only fails on new ones. Zero runtime dependencies.
|
|
56
|
+
|
|
57
|
+
## Quick start
|
|
58
|
+
|
|
59
|
+
Requires Node.js 20 or later.
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
# run once, no install
|
|
63
|
+
npx midnight-shield contracts/
|
|
64
|
+
|
|
65
|
+
# or add it to your project
|
|
66
|
+
npm install --save-dev midnight-shield
|
|
67
|
+
npx midnight-shield contracts/
|
|
68
|
+
|
|
69
|
+
# or install globally
|
|
70
|
+
npm install -g midnight-shield
|
|
71
|
+
midnight-shield contracts/
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
> If the npm package is not available yet, use `npx github:efforthye/midnight-shield contracts/`.
|
|
75
|
+
|
|
76
|
+
Not ready to install anything? Paste a contract into the **[web playground](#web-playground)**.
|
|
77
|
+
|
|
78
|
+
The repository has examples: [`examples/vulnerable.compact`](examples/vulnerable.compact) triggers every Compact rule, [`examples/dapp/vulnerable.ts`](examples/dapp/vulnerable.ts) every TypeScript rule, and the `safe` versions show the fixes (0 findings).
|
|
79
|
+
|
|
80
|
+
## Web playground
|
|
81
|
+
|
|
82
|
+
**[efforthye.github.io/midnight-shield](https://efforthye.github.io/midnight-shield/)**
|
|
83
|
+
|
|
84
|
+
The full analyzer, compiled to run in the browser. Paste a Compact contract or DApp TypeScript and see findings as you type. Nothing is uploaded: there is no server, so private contract code stays on your machine.
|
|
85
|
+
|
|
86
|
+
| Findings with fixes | Disclosure map |
|
|
87
|
+
| --- | --- |
|
|
88
|
+
| <img src="https://raw.githubusercontent.com/efforthye/midnight-shield/main/docs/assets/playground.png" alt="Playground findings" width="400"> | <img src="https://raw.githubusercontent.com/efforthye/midnight-shield/main/docs/assets/playground-disclosures.png" alt="Playground disclosure map" width="400"> |
|
|
89
|
+
|
|
90
|
+
- **Live analysis** of `.compact` and `.ts` code, with problem lines marked in the editor gutter
|
|
91
|
+
- **Disclosure map** tab: every value that becomes public, and whether it is raw, hashed or committed
|
|
92
|
+
- **Examples** to start from: a vulnerable contract, its safe version, and vulnerable DApp code
|
|
93
|
+
- **Share link**: the code is stored in the URL hash, so you can send a finding to a teammate or reviewer
|
|
94
|
+
- **Download report** as Markdown for an audit note or a PR comment
|
|
95
|
+
- Severity filter, light and dark themes, and a mobile layout
|
|
96
|
+
|
|
97
|
+
<img src="https://raw.githubusercontent.com/efforthye/midnight-shield/main/docs/assets/playground-light.png" alt="Playground checking TypeScript DApp code in light theme" width="820">
|
|
98
|
+
|
|
99
|
+
To run it locally: `npm run playground` builds a single file at `playground/dist/index.html` that you can open directly.
|
|
100
|
+
|
|
101
|
+
## Usage guide
|
|
102
|
+
|
|
103
|
+
### 1. Scan
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
npx midnight-shield contracts/ # .compact files and the DApp's .ts/.js files
|
|
107
|
+
npx midnight-shield contracts/ --no-sdk # only .compact files
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
Midnight Shield skips `node_modules`, `dist`, `build`, compiler output and, for TypeScript checks, test files. It follows `import "..."` into other Compact files.
|
|
111
|
+
|
|
112
|
+
### 2. Read a finding
|
|
113
|
+
|
|
114
|
+
Each finding shows its **severity**, **rule**, **location** (clickable in most terminals), **confidence** when it is not high, the **message** with the fix, a **code frame**, and a link to the rule page.
|
|
115
|
+
|
|
116
|
+
```bash
|
|
117
|
+
npx midnight-shield explain MS009 # read a rule's documentation in the terminal
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
### 3. Fix and scan again
|
|
121
|
+
|
|
122
|
+
Every rule page shows a vulnerable and a fixed example. Safe fixes can be applied automatically:
|
|
123
|
+
|
|
124
|
+
```bash
|
|
125
|
+
npx midnight-shield contracts/ --fix-dry-run # see what would change
|
|
126
|
+
npx midnight-shield contracts/ --fix # apply
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
Only fixes that cannot change what a contract does are automatic (today: adding a missing `pragma`). Fixes that change hashes or commitments would change on-chain values, so they are left to you or to the [AI skill](#use-with-ai-coding-agents).
|
|
130
|
+
|
|
131
|
+
<img src="https://raw.githubusercontent.com/efforthye/midnight-shield/main/docs/assets/safe.png" alt="No findings" width="820">
|
|
132
|
+
|
|
133
|
+
### 4. Adopt it in an existing project
|
|
134
|
+
|
|
135
|
+
Accept today's findings and fail CI only on new ones:
|
|
136
|
+
|
|
137
|
+
```bash
|
|
138
|
+
npx midnight-shield contracts/ --write-baseline .midnight-shield-baseline.json
|
|
139
|
+
npx midnight-shield contracts/ --baseline .midnight-shield-baseline.json
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
Baseline entries are matched by a fingerprint of the rule and the code line, so moving code around does not break them. `--show-suppressed` lists everything that is hidden by a baseline or an inline comment, for audits.
|
|
143
|
+
|
|
144
|
+
### 5. Configure
|
|
145
|
+
|
|
146
|
+
```bash
|
|
147
|
+
npx midnight-shield --init # creates midnight-shield.config.json
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
```json
|
|
151
|
+
{
|
|
152
|
+
"disable": [],
|
|
153
|
+
"failOn": "high",
|
|
154
|
+
"minSeverity": "info",
|
|
155
|
+
"minConfidence": "low",
|
|
156
|
+
"ignore": ["**/test/**"],
|
|
157
|
+
"baseline": ".midnight-shield-baseline.json",
|
|
158
|
+
"plugins": ["./tools/our-rules.mjs"],
|
|
159
|
+
"sdk": true
|
|
160
|
+
}
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
To silence one finding in code, say why next to it:
|
|
164
|
+
|
|
165
|
+
```compact
|
|
166
|
+
// shield-disable-next-line MS005 -- the tag is supplied by every caller
|
|
167
|
+
const h = persistentHash<Vector<2, Bytes<32>>>([tag, sk]);
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
`shield-disable-line` and `shield-disable-file` work the same way. Leave out the rule ID to suppress every rule.
|
|
171
|
+
|
|
172
|
+
### 6. Report
|
|
173
|
+
|
|
174
|
+
```bash
|
|
175
|
+
npx midnight-shield contracts/ --format markdown -o report.md # audit or PR report
|
|
176
|
+
npx midnight-shield contracts/ --format sarif -o results.sarif # GitHub code scanning
|
|
177
|
+
npx midnight-shield contracts/ --format json # scripts and AI agents
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
## Rules
|
|
181
|
+
|
|
182
|
+
<img src="https://raw.githubusercontent.com/efforthye/midnight-shield/main/docs/assets/rules.png" alt="midnight-shield --list-rules" width="820">
|
|
183
|
+
|
|
184
|
+
**Compact contracts**
|
|
185
|
+
|
|
186
|
+
| ID | Name | Severity | Confidence | Finds |
|
|
187
|
+
| --- | --- | --- | --- | --- |
|
|
188
|
+
| [MS001](docs/rules/MS001.md) | `own-public-key-auth` | 🟣 Critical | high | `ownPublicKey()` compared to a key to authorize the caller, including through helper circuits |
|
|
189
|
+
| [MS002](docs/rules/MS002.md) | `unconstrained-witness` | 🟡 Medium | medium | A witness value reaches public state with no `assert` that checks it |
|
|
190
|
+
| [MS003](docs/rules/MS003.md) | `low-entropy-hash` | 🔴 High | medium | A hash of only low-entropy private values (vote, age, PIN) made public |
|
|
191
|
+
| [MS004](docs/rules/MS004.md) | `weak-commitment-randomness` | 🔴 High | high | A commitment with constant, public, short, or reused randomness |
|
|
192
|
+
| [MS005](docs/rules/MS005.md) | `missing-domain-separation` | 🔵 Low | medium | A hash of private data with no constant domain tag |
|
|
193
|
+
| [MS006](docs/rules/MS006.md) | `missing-pragma` | ⚪ Info | high | No `pragma language_version` (auto-fixable) |
|
|
194
|
+
| [MS007](docs/rules/MS007.md) | `disclosed-secret` | 🔴 High | low | The raw value of a secret key, seed, or password is made public |
|
|
195
|
+
| [MS008](docs/rules/MS008.md) | `missing-nullifier` | 🟡 Medium | low | Merkle-authorized state change with no nullifier, so it can be repeated |
|
|
196
|
+
| [MS009](docs/rules/MS009.md) | `unbound-merkle-path` | 🔴 High | high | Merkle root checked, but the path's leaf is never tied to the caller |
|
|
197
|
+
| [MS010](docs/rules/MS010.md) | `linkable-ledger-update` | 🟡 Medium | medium | In an anonymous-membership contract, the same secret-derived tag is published by several circuits |
|
|
198
|
+
|
|
199
|
+
**DApp code (TypeScript / JavaScript)**
|
|
200
|
+
|
|
201
|
+
| ID | Name | Severity | Confidence | Finds |
|
|
202
|
+
| --- | --- | --- | --- | --- |
|
|
203
|
+
| [MS101](docs/rules/MS101.md) | `remote-proof-server` | 🟣 Critical | medium | The proof server URL points to a remote host |
|
|
204
|
+
| [MS102](docs/rules/MS102.md) | `secret-in-log` | 🔴 High | medium | A seed, secret key or password passed to a log call |
|
|
205
|
+
|
|
206
|
+
Need a rule for your own conventions? [Write a plugin](docs/custom-rules.md).
|
|
207
|
+
|
|
208
|
+
## Disclosure map
|
|
209
|
+
|
|
210
|
+
On Midnight, everything that becomes public is explicit. The disclosure map lists all of it in one place, so a reviewer can check the privacy of a contract in minutes:
|
|
211
|
+
|
|
212
|
+
```bash
|
|
213
|
+
npx midnight-shield contracts/ --print disclosures
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
<img src="https://raw.githubusercontent.com/efforthye/midnight-shield/main/docs/assets/disclosures.png" alt="Disclosure map" width="820">
|
|
217
|
+
|
|
218
|
+
`RAW` means private data is published as is. That is sometimes intended (a public balance), but every `RAW` row deserves a second look. The map is also available as JSON and Markdown (`--format json|markdown`), in the playground, and in VS Code.
|
|
219
|
+
|
|
220
|
+
## How it works
|
|
221
|
+
|
|
222
|
+
```mermaid
|
|
223
|
+
flowchart LR
|
|
224
|
+
A[".compact files"] --> B["Lexer"]
|
|
225
|
+
B --> C["Parser<br/>(syntax tree)"]
|
|
226
|
+
I["Imported modules"] --> D
|
|
227
|
+
C --> D["Data-flow analyzer"]
|
|
228
|
+
D --> E["Rules MS001-MS010<br/>+ plugins"]
|
|
229
|
+
T[".ts / .js files"] --> S["SDK checks<br/>MS101-MS102"]
|
|
230
|
+
E --> F["Config, baseline,<br/>suppressions"]
|
|
231
|
+
S --> F
|
|
232
|
+
D --> M["Disclosure map"]
|
|
233
|
+
F --> G["Text / JSON / SARIF / Markdown<br/>VS Code / Playground"]
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
For every circuit, the analyzer evaluates each expression to a summary of where its value came from:
|
|
237
|
+
|
|
238
|
+
| Source | Example | Treated as |
|
|
239
|
+
| --- | --- | --- |
|
|
240
|
+
| Witness | `secretKey()` | Private, prover-controlled |
|
|
241
|
+
| Circuit parameter | `amount: Uint<64>` | Private |
|
|
242
|
+
| Ledger state | `owner`, `balances.lookup(k)` | Public |
|
|
243
|
+
| Constant | `pad(32, "app:")`, `default<Bytes<32>>`, enum members | Public, zero entropy |
|
|
244
|
+
| `disclose(x)` | | Public from this point on |
|
|
245
|
+
|
|
246
|
+
Secret entropy is estimated from types (`Boolean` = 1 bit, `Uint<16>` = 16, `Bytes<32>` = 256). Calls to circuits in the same file or in imported modules are evaluated with the caller's arguments, so a check hidden in a helper is still found.
|
|
247
|
+
|
|
248
|
+
The rules follow the [Midnight security best practices](https://docs.midnight.network/guides/security-best-practices) and the [explicit disclosure](https://docs.midnight.network/compact/explicit_disclosure) rules.
|
|
249
|
+
|
|
250
|
+
## VS Code
|
|
251
|
+
|
|
252
|
+
The extension in [`vscode/`](vscode) shows findings as you type, with links to each rule, a **Scan workspace** command and a **Show disclosure map** command. It reads `midnight-shield.config.json` and inline suppressions. See [`vscode/README.md`](vscode/README.md) to build and install it.
|
|
253
|
+
|
|
254
|
+
## GitHub Action
|
|
255
|
+
|
|
256
|
+
```yaml
|
|
257
|
+
# .github/workflows/midnight-shield.yml
|
|
258
|
+
name: Midnight Shield
|
|
259
|
+
on: [push, pull_request]
|
|
260
|
+
|
|
261
|
+
jobs:
|
|
262
|
+
scan:
|
|
263
|
+
runs-on: ubuntu-latest
|
|
264
|
+
permissions:
|
|
265
|
+
contents: read
|
|
266
|
+
security-events: write # show results in the Security tab
|
|
267
|
+
steps:
|
|
268
|
+
- uses: actions/checkout@v4
|
|
269
|
+
- uses: efforthye/midnight-shield@main
|
|
270
|
+
with:
|
|
271
|
+
path: contracts
|
|
272
|
+
fail-on: high
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
Findings appear in **Security → Code scanning** and as annotations on pull requests.
|
|
276
|
+
|
|
277
|
+
| Input | Default | Description |
|
|
278
|
+
| --- | --- | --- |
|
|
279
|
+
| `path` | `.` | Files or folders to scan |
|
|
280
|
+
| `fail-on` | `high` | Fail the job at or above this severity (`none` to never fail) |
|
|
281
|
+
| `upload-sarif` | `true` | Upload results to GitHub code scanning |
|
|
282
|
+
|
|
283
|
+
## Use with AI coding agents
|
|
284
|
+
|
|
285
|
+
### Claude Code skill
|
|
286
|
+
|
|
287
|
+
[`skills/midnight-shield`](skills/midnight-shield/SKILL.md) teaches Claude Code to scan, fix findings in order of severity, check the disclosure map, and re-scan until the contract is clean:
|
|
288
|
+
|
|
289
|
+
```bash
|
|
290
|
+
mkdir -p .claude/skills
|
|
291
|
+
cp -r node_modules/midnight-shield/skills/midnight-shield .claude/skills/
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
### JSON and the library API
|
|
295
|
+
|
|
296
|
+
```bash
|
|
297
|
+
npx midnight-shield contracts/ --format json --fail-on none
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
```ts
|
|
301
|
+
import { lintSource, mapDisclosures } from "midnight-shield";
|
|
302
|
+
|
|
303
|
+
const findings = lintSource(source, "counter.compact");
|
|
304
|
+
const publicData = mapDisclosures(source, "counter.compact");
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
## CLI reference
|
|
308
|
+
|
|
309
|
+
```text
|
|
310
|
+
midnight-shield [paths...] [options]
|
|
311
|
+
midnight-shield explain <RULE>
|
|
312
|
+
midnight-shield --init
|
|
313
|
+
|
|
314
|
+
Output: -f, --format text|json|sarif|markdown -o, --output <file>
|
|
315
|
+
--print disclosures --no-code-frame --no-color
|
|
316
|
+
Filtering: --fail-on <severity> --min-severity <severity> --min-confidence <confidence>
|
|
317
|
+
--disable <IDs> --ignore <glob> --no-sdk --show-suppressed
|
|
318
|
+
Adoption: --baseline <file> --write-baseline <file> --fix --fix-dry-run
|
|
319
|
+
-c, --config <file> --plugin <module>
|
|
320
|
+
Other: --list-rules -v, --version -h, --help
|
|
321
|
+
```
|
|
322
|
+
|
|
323
|
+
Exit codes: `0` no blocking findings, `1` findings at or above `--fail-on`, `2` usage or config error.
|
|
324
|
+
|
|
325
|
+
## How it compares
|
|
326
|
+
|
|
327
|
+
| | Compact compiler | [Night Check](https://github.com/CjDabrow/night-check) | **Midnight Shield** |
|
|
328
|
+
| --- | --- | --- | --- |
|
|
329
|
+
| Blocks undeclared witness disclosure | ✅ | | (left to the compiler) |
|
|
330
|
+
| Analysis method | Type checker | Line-by-line patterns | Syntax tree + data flow |
|
|
331
|
+
| Follows values across helper circuits and imports | | | ✅ |
|
|
332
|
+
| Entropy-aware hash and commitment checks | | | ✅ |
|
|
333
|
+
| Disclosure map | | | ✅ |
|
|
334
|
+
| TypeScript/DApp checks | | ✅ | ✅ |
|
|
335
|
+
| Severity + confidence | | Severity | ✅ |
|
|
336
|
+
| Baselines, suppressions, config | | | ✅ |
|
|
337
|
+
| CLI · GitHub Action + SARIF · VS Code | ✅ · · | Demo script | ✅ · ✅ · ✅ |
|
|
338
|
+
| Web UI | | ✅ (with on-chain review receipt) | ✅ (local only) |
|
|
339
|
+
| AI agent skill · plugin API | | | ✅ · ✅ |
|
|
340
|
+
| Verified against real Midnight code in CI | n/a | | ✅ |
|
|
341
|
+
|
|
342
|
+
## Testing and verification
|
|
343
|
+
|
|
344
|
+
| Check | What it proves | Command |
|
|
345
|
+
| --- | --- | --- |
|
|
346
|
+
| **Unit and integration tests** (120 tests, 96% line coverage of `src/`) | Lexer, parser, every rule (flagged and not-flagged cases), reporters, CLI, baselines, plugins, fixes | `npm test`, `npm run coverage` |
|
|
347
|
+
| **Fuzz tests** | Random token edits, truncations, random bytes, deep nesting and recursive circuits never crash the analyzer | part of `npm test` |
|
|
348
|
+
| **Corpus verification** | 1,052 real files (Compact and TypeScript) at pinned commits: zero parse errors, no medium-or-worse findings, results match a reviewed baseline | `npm run verify` |
|
|
349
|
+
| **Real compiler** | The example contracts compile with the official `compact` toolchain | CI job `compile-examples` |
|
|
350
|
+
| **Package** | The npm tarball installs and the CLI runs | CI job `package` |
|
|
351
|
+
|
|
352
|
+
<img src="https://raw.githubusercontent.com/efforthye/midnight-shield/main/docs/assets/verify.png" alt="Corpus verification output" width="720">
|
|
353
|
+
|
|
354
|
+
## Roadmap
|
|
355
|
+
|
|
356
|
+
- [x] **v0.1** Parser, data-flow analysis, CLI, GitHub Action, SARIF
|
|
357
|
+
- [x] **v0.2** Imported modules, code frames, config file, Claude Code skill
|
|
358
|
+
- [x] **v0.3** Merkle and secret rules, corpus verification, real-compiler CI
|
|
359
|
+
- [x] **v0.4** Disclosure map, confidence, baselines, Markdown, plugins, autofix, TypeScript checks, playground, VS Code extension, npm package
|
|
360
|
+
- [ ] VS Code Marketplace release
|
|
361
|
+
- [ ] Data-flow facts for plugins
|
|
362
|
+
- [ ] More rules from community feedback
|
|
363
|
+
|
|
364
|
+
Ideas and false-positive reports are welcome in [Issues](https://github.com/efforthye/midnight-shield/issues).
|
|
365
|
+
|
|
366
|
+
## Development
|
|
367
|
+
|
|
368
|
+
```bash
|
|
369
|
+
npm install
|
|
370
|
+
npm test # build + tests
|
|
371
|
+
npm run coverage # tests with coverage
|
|
372
|
+
npm run verify # scan real Midnight code and compare with the baseline
|
|
373
|
+
npm run playground # build the web playground into playground/dist
|
|
374
|
+
npm run demo # scan examples/
|
|
375
|
+
```
|
|
376
|
+
|
|
377
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md) and [CHANGELOG.md](CHANGELOG.md).
|
|
378
|
+
|
|
379
|
+
## Acknowledgements
|
|
380
|
+
|
|
381
|
+
Several initial rule ideas come from [Night Check](https://github.com/CjDabrow/night-check) (MIT). Feature ideas from [Slither](https://github.com/crytic/slither), [Aderyn](https://github.com/Cyfrin/aderyn), [Circomspect](https://github.com/trailofbits/circomspect) and aztec-lint. Built as part of **KR NightForce Cohort 2** (Builder track).
|
|
382
|
+
|
|
383
|
+
## License
|
|
384
|
+
|
|
385
|
+
[MIT](LICENSE)
|
package/action.yml
ADDED
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
name: Midnight Shield
|
|
2
|
+
description: Static analysis for Midnight Compact contracts. Finds security and privacy issues before deploy.
|
|
3
|
+
author: efforthye
|
|
4
|
+
branding:
|
|
5
|
+
icon: shield
|
|
6
|
+
color: purple
|
|
7
|
+
|
|
8
|
+
inputs:
|
|
9
|
+
path:
|
|
10
|
+
description: Files or directories to scan (space-separated)
|
|
11
|
+
default: "."
|
|
12
|
+
fail-on:
|
|
13
|
+
description: Fail the step if a finding is at or above this severity (critical, high, medium, low, info, none)
|
|
14
|
+
default: "high"
|
|
15
|
+
upload-sarif:
|
|
16
|
+
description: Upload results to GitHub code scanning (requires security-events write permission)
|
|
17
|
+
default: "true"
|
|
18
|
+
|
|
19
|
+
runs:
|
|
20
|
+
using: composite
|
|
21
|
+
steps:
|
|
22
|
+
- uses: actions/setup-node@v4
|
|
23
|
+
with:
|
|
24
|
+
node-version: 20
|
|
25
|
+
|
|
26
|
+
- name: Build Midnight Shield
|
|
27
|
+
shell: bash
|
|
28
|
+
working-directory: ${{ github.action_path }}
|
|
29
|
+
run: |
|
|
30
|
+
npm ci --no-audit --no-fund
|
|
31
|
+
npm run build
|
|
32
|
+
|
|
33
|
+
- name: Scan Compact contracts
|
|
34
|
+
id: scan
|
|
35
|
+
shell: bash
|
|
36
|
+
env:
|
|
37
|
+
SCAN_PATH: ${{ inputs.path }}
|
|
38
|
+
FAIL_ON: ${{ inputs.fail-on }}
|
|
39
|
+
run: |
|
|
40
|
+
set +e
|
|
41
|
+
# shellcheck disable=SC2086
|
|
42
|
+
node "$GITHUB_ACTION_PATH/dist/src/cli.js" $SCAN_PATH --format sarif --output midnight-shield.sarif --fail-on "$FAIL_ON"
|
|
43
|
+
echo "exit-code=$?" >> "$GITHUB_OUTPUT"
|
|
44
|
+
|
|
45
|
+
- name: Upload SARIF
|
|
46
|
+
if: inputs.upload-sarif == 'true'
|
|
47
|
+
uses: github/codeql-action/upload-sarif@v3
|
|
48
|
+
with:
|
|
49
|
+
sarif_file: midnight-shield.sarif
|
|
50
|
+
category: midnight-shield
|
|
51
|
+
|
|
52
|
+
- name: Check result
|
|
53
|
+
shell: bash
|
|
54
|
+
env:
|
|
55
|
+
EXIT_CODE: ${{ steps.scan.outputs.exit-code }}
|
|
56
|
+
run: exit "$EXIT_CODE"
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
import type { Expr, Loc, Program } from "./ast.js";
|
|
2
|
+
import { type Confidence, type Severity } from "./rules.js";
|
|
3
|
+
export interface RawFinding {
|
|
4
|
+
ruleId: string;
|
|
5
|
+
severity: Severity;
|
|
6
|
+
confidence: Confidence;
|
|
7
|
+
message: string;
|
|
8
|
+
loc: Loc;
|
|
9
|
+
}
|
|
10
|
+
export type Protection = "raw" | "hash" | "commit" | "public" | "constant";
|
|
11
|
+
/** A point where data becomes public: disclose(), a ledger write, or an exported circuit's return value. */
|
|
12
|
+
export interface DisclosureEvent {
|
|
13
|
+
circuit: string;
|
|
14
|
+
loc: Loc;
|
|
15
|
+
via: "disclose" | "ledger write" | "return";
|
|
16
|
+
/** ledger field written, when known */
|
|
17
|
+
target?: string;
|
|
18
|
+
/** private inputs that flow into the public value: "witness:sk", "param:amount" */
|
|
19
|
+
sources: string[];
|
|
20
|
+
protection: Protection;
|
|
21
|
+
/** estimated secret entropy in bits (undefined = unknown or high) */
|
|
22
|
+
secretBits?: number;
|
|
23
|
+
}
|
|
24
|
+
/** Does an identifier look like it names a secret? (`secretKey`, `localSk`, `_secret`, `privateKey`) */
|
|
25
|
+
export declare function isSecretName(name: string): boolean;
|
|
26
|
+
/** Resolves an `import "path"` or `include "path"` to a parsed program. */
|
|
27
|
+
export type ImportResolver = (fromFile: string | undefined, target: string) => {
|
|
28
|
+
file: string;
|
|
29
|
+
program: Program;
|
|
30
|
+
} | undefined;
|
|
31
|
+
export declare class Analyzer {
|
|
32
|
+
private program;
|
|
33
|
+
private resolver?;
|
|
34
|
+
private file?;
|
|
35
|
+
private ledgers;
|
|
36
|
+
private witnesses;
|
|
37
|
+
private circuits;
|
|
38
|
+
private visitedFiles;
|
|
39
|
+
private enums;
|
|
40
|
+
private structs;
|
|
41
|
+
private aliases;
|
|
42
|
+
private findings;
|
|
43
|
+
private seen;
|
|
44
|
+
private constrainedWitnesses;
|
|
45
|
+
private witnessSinks;
|
|
46
|
+
private hashSites;
|
|
47
|
+
/** MS010: identity key -> circuits that publish it (first location per circuit) */
|
|
48
|
+
private identityUses;
|
|
49
|
+
/** exported circuits that authorize with anonymous Merkle membership */
|
|
50
|
+
private anonymousCircuits;
|
|
51
|
+
constructor(program: Program, resolver?: ImportResolver | undefined, file?: string | undefined);
|
|
52
|
+
/**
|
|
53
|
+
* Register declarations. Imported modules are registered under their import
|
|
54
|
+
* prefix (e.g. `Utils_hash`) so calls from the analyzed file resolve, and
|
|
55
|
+
* marked external: they are followed when called, but not reported on.
|
|
56
|
+
*/
|
|
57
|
+
private collect;
|
|
58
|
+
/** Resolve a name used inside code of the module with `frame.prefix`. */
|
|
59
|
+
private resolveName;
|
|
60
|
+
run(): RawFinding[];
|
|
61
|
+
/**
|
|
62
|
+
* MS002 targets witnesses that report facts (amounts, flags, states, records).
|
|
63
|
+
* Free-form user input (Bytes, Opaque) and randomness are expected to be
|
|
64
|
+
* unconstrained, so they are skipped to avoid noise.
|
|
65
|
+
*/
|
|
66
|
+
private isFactualWitness;
|
|
67
|
+
private isFactualType;
|
|
68
|
+
private analyzeDecls;
|
|
69
|
+
private analyzeFunction;
|
|
70
|
+
private paramInfo;
|
|
71
|
+
private report;
|
|
72
|
+
private disclosures;
|
|
73
|
+
getDisclosures(): DisclosureEvent[];
|
|
74
|
+
private recordDisclosure;
|
|
75
|
+
private typeBits;
|
|
76
|
+
private lookup;
|
|
77
|
+
private execBlock;
|
|
78
|
+
private execStmt;
|
|
79
|
+
private markConstrained;
|
|
80
|
+
/** A value becomes public here (disclose() or a ledger write). */
|
|
81
|
+
private sink;
|
|
82
|
+
private evalExpr;
|
|
83
|
+
private evalIdent;
|
|
84
|
+
private ownpkCompare;
|
|
85
|
+
private evalCall;
|
|
86
|
+
/** MS008: look for Merkle membership proofs and nullifier checks inside an assert condition. */
|
|
87
|
+
private scanAuthorization;
|
|
88
|
+
/** Paths are tracked by name within one top-level circuit; helper frames get their own namespace. */
|
|
89
|
+
private pathKey;
|
|
90
|
+
private evalLambda;
|
|
91
|
+
/** Flatten the inputs of a hash: vector literals and struct literals become their elements. */
|
|
92
|
+
private hashInputs;
|
|
93
|
+
private evalHash;
|
|
94
|
+
private evalCommit;
|
|
95
|
+
private inlineCircuit;
|
|
96
|
+
}
|
|
97
|
+
export declare function exprText(e: Expr): string;
|