relsec 0.1.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/LICENSE +21 -0
- package/README.md +376 -0
- package/SECURITY.md +36 -0
- package/dist/advisories.d.ts +5 -0
- package/dist/advisories.js +111 -0
- package/dist/advisories.js.map +1 -0
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +181 -0
- package/dist/cli.js.map +1 -0
- package/dist/config.d.ts +15 -0
- package/dist/config.js +50 -0
- package/dist/config.js.map +1 -0
- package/dist/engine.d.ts +8 -0
- package/dist/engine.js +76 -0
- package/dist/engine.js.map +1 -0
- package/dist/interactive.d.ts +58 -0
- package/dist/interactive.js +698 -0
- package/dist/interactive.js.map +1 -0
- package/dist/inventory.d.ts +3 -0
- package/dist/inventory.js +27 -0
- package/dist/inventory.js.map +1 -0
- package/dist/ioc.d.ts +16 -0
- package/dist/ioc.js +46 -0
- package/dist/ioc.js.map +1 -0
- package/dist/manifests.d.ts +10 -0
- package/dist/manifests.js +157 -0
- package/dist/manifests.js.map +1 -0
- package/dist/osv.d.ts +13 -0
- package/dist/osv.js +82 -0
- package/dist/osv.js.map +1 -0
- package/dist/reachability.d.ts +6 -0
- package/dist/reachability.js +19 -0
- package/dist/reachability.js.map +1 -0
- package/dist/report.d.ts +4 -0
- package/dist/report.js +74 -0
- package/dist/report.js.map +1 -0
- package/dist/security-modules.d.ts +14 -0
- package/dist/security-modules.js +126 -0
- package/dist/security-modules.js.map +1 -0
- package/dist/theme.d.ts +43 -0
- package/dist/theme.js +191 -0
- package/dist/theme.js.map +1 -0
- package/dist/types.d.ts +37 -0
- package/dist/types.js +2 -0
- package/dist/types.js.map +1 -0
- package/dist/version-info.d.ts +1 -0
- package/dist/version-info.js +2 -0
- package/dist/version-info.js.map +1 -0
- package/dist/version.d.ts +4 -0
- package/dist/version.js +74 -0
- package/dist/version.js.map +1 -0
- package/docs/RELEASE.md +41 -0
- package/package.json +64 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026
|
|
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
ADDED
|
@@ -0,0 +1,376 @@
|
|
|
1
|
+
# relevant
|
|
2
|
+
|
|
3
|
+
[](https://github.com/MistanKh/relsec/actions/workflows/ci.yml)
|
|
4
|
+
[](LICENSE)
|
|
5
|
+
[](package.json)
|
|
6
|
+
|
|
7
|
+
Local-first security relevance for CVEs, advisories, IOCs, dependencies, logs, and service exposure.
|
|
8
|
+
|
|
9
|
+
`relevant` helps answer the question most scanners leave to humans:
|
|
10
|
+
|
|
11
|
+
> Does this finding actually matter in this environment?
|
|
12
|
+
|
|
13
|
+
It is an open-source alpha for security engineers, AppSec teams, SOC analysts, platform teams, and curious builders who want evidence-first triage without sending code, logs, or inventories to a hosted service.
|
|
14
|
+
|
|
15
|
+
The package name is `relsec`, and the CLI is exposed as both `relevant` and `relsec`.
|
|
16
|
+
|
|
17
|
+
## The Problem
|
|
18
|
+
|
|
19
|
+
Modern teams receive security findings faster than they can investigate them:
|
|
20
|
+
|
|
21
|
+
- A scanner says a dependency is vulnerable.
|
|
22
|
+
- A vendor advisory says a package needs urgent patching.
|
|
23
|
+
- A threat feed publishes IPs, domains, hashes, or other indicators.
|
|
24
|
+
- A SOC alert references activity that may or may not exist in local logs.
|
|
25
|
+
- A spreadsheet says a service is internet-facing, but nobody is sure which repo owns it.
|
|
26
|
+
|
|
27
|
+
The hard part is not seeing the alert. The hard part is proving whether it matters in your environment.
|
|
28
|
+
|
|
29
|
+
For example, imagine a critical upload-library CVE lands during a release freeze. A scanner flags `multer` somewhere in your monorepo. Before waking up every service owner, you need answers:
|
|
30
|
+
|
|
31
|
+
- Which service actually has the vulnerable version?
|
|
32
|
+
- Is that service internet-facing or internal-only?
|
|
33
|
+
- Is the vulnerable upload API used in source code?
|
|
34
|
+
- What evidence can be pasted into a ticket?
|
|
35
|
+
- What should be done next?
|
|
36
|
+
|
|
37
|
+
`relevant` turns that into a local evidence-gathering workflow instead of a meeting.
|
|
38
|
+
|
|
39
|
+
## What This Tool Does
|
|
40
|
+
|
|
41
|
+
`relevant` reads local files and connects several pieces of security context:
|
|
42
|
+
|
|
43
|
+
| Input | What it uses it for |
|
|
44
|
+
| --- | --- |
|
|
45
|
+
| Dependency manifests | Finds vulnerable package versions in `package-lock.json`, `requirements.txt`, and SBOM files. |
|
|
46
|
+
| Advisory data | Maps CVEs, GHSA IDs, or imported OSV records to affected packages, ranges, and risky symbols. |
|
|
47
|
+
| Service inventory | Understands whether a service is internet-facing, partner-facing, internal, or unknown. |
|
|
48
|
+
| Source code | Searches for vulnerable symbols or APIs that make a package actually reachable. |
|
|
49
|
+
| Logs | Matches IOCs against local log files, including gzip-compressed logs. |
|
|
50
|
+
| Reports | Produces terminal, JSON, JSONL, Markdown, and SARIF output for humans and automation. |
|
|
51
|
+
|
|
52
|
+
It does not try to replace a scanner. It helps explain scanner output with local evidence.
|
|
53
|
+
|
|
54
|
+
## Real-World Examples
|
|
55
|
+
|
|
56
|
+
### Example 1: Triage A Dependency CVE
|
|
57
|
+
|
|
58
|
+
You receive a CVE for a vulnerable upload parser. Your scanner reports that `multer` exists somewhere in the repo.
|
|
59
|
+
|
|
60
|
+
Run:
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
relevant cve CVE-2026-41001 \
|
|
64
|
+
--workspace examples/enterprise \
|
|
65
|
+
--inventory examples/enterprise/security/inventory.json \
|
|
66
|
+
--format markdown
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
`relevant` checks:
|
|
70
|
+
|
|
71
|
+
1. Is there a local advisory record for the CVE?
|
|
72
|
+
2. Which package and version range are affected?
|
|
73
|
+
3. Which services contain the vulnerable package version?
|
|
74
|
+
4. Are those services exposed?
|
|
75
|
+
5. Does source code reference vulnerable symbols such as `upload.single` or `multer(`?
|
|
76
|
+
|
|
77
|
+
Example result:
|
|
78
|
+
|
|
79
|
+
```txt
|
|
80
|
+
CVE-2026-41001: relevant (critical)
|
|
81
|
+
|
|
82
|
+
Evidence:
|
|
83
|
+
- Found multer 1.4.4 in services/checkout-api/package-lock.json.
|
|
84
|
+
- Reachable symbol upload.single in src/uploads.ts.
|
|
85
|
+
- checkout-api has public ingress: https://checkout.example.com/v1/receipts.
|
|
86
|
+
|
|
87
|
+
Recommended actions:
|
|
88
|
+
- Upgrade multer to >=1.4.5-lts.1.
|
|
89
|
+
- Restrict public upload endpoints until patched.
|
|
90
|
+
- Search access logs for unusual multipart upload paths.
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
That output gives AppSec, engineering, and incident response a shared artifact: vulnerable dependency, reachable code path, exposed service, and suggested next actions.
|
|
94
|
+
|
|
95
|
+
### Example 2: Check Whether Threat Indicators Appear In Logs
|
|
96
|
+
|
|
97
|
+
A threat report publishes suspicious IPs and domains. You want to know whether those indicators appear in local Okta, proxy, CloudTrail, or server logs.
|
|
98
|
+
|
|
99
|
+
Run:
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
relevant ioc \
|
|
103
|
+
--indicators examples/enterprise/security/cisa-aa26-141a.iocs \
|
|
104
|
+
--logs examples/enterprise/security/logs/okta-auth-prod-2026-05-21.log \
|
|
105
|
+
--logs examples/enterprise/security/logs/zscaler-web-prod-2026-05-21.log \
|
|
106
|
+
--format json
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Example result:
|
|
110
|
+
|
|
111
|
+
```json
|
|
112
|
+
{
|
|
113
|
+
"totalMatches": 2,
|
|
114
|
+
"matches": [
|
|
115
|
+
{
|
|
116
|
+
"indicator": "203.0.113.77",
|
|
117
|
+
"type": "ip",
|
|
118
|
+
"line": 3
|
|
119
|
+
},
|
|
120
|
+
{
|
|
121
|
+
"indicator": "evil-update.example",
|
|
122
|
+
"type": "domain",
|
|
123
|
+
"line": 1
|
|
124
|
+
}
|
|
125
|
+
]
|
|
126
|
+
}
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
That helps a SOC analyst quickly move from "this IOC exists in a feed" to "this IOC appears in these local files on these lines."
|
|
130
|
+
|
|
131
|
+
### Example 3: Build A Local Advisory File From OSV
|
|
132
|
+
|
|
133
|
+
When you want broader advisory coverage, import OSV records for dependencies found in your inventory:
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
relevant import osv \
|
|
137
|
+
--workspace examples/enterprise \
|
|
138
|
+
--inventory examples/enterprise/security/inventory.json \
|
|
139
|
+
--output examples/enterprise/security/osv-advisories.json
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
After that, later CVE/GHSA checks can use the local file without calling OSV again:
|
|
143
|
+
|
|
144
|
+
```bash
|
|
145
|
+
relevant cve GHSA-example-id \
|
|
146
|
+
--workspace examples/enterprise \
|
|
147
|
+
--inventory examples/enterprise/security/inventory.json \
|
|
148
|
+
--advisories examples/enterprise/security/osv-advisories.json
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
## Status
|
|
152
|
+
|
|
153
|
+
This project is a **developer preview**. It is useful today for local experiments, demos, evidence collection, and early workflow design, but it is not a replacement for a vulnerability management platform, SIEM, SCA product, or incident response process.
|
|
154
|
+
|
|
155
|
+
What is ready:
|
|
156
|
+
|
|
157
|
+
- Deterministic local CVE relevance checks.
|
|
158
|
+
- Local IOC matching across plain and gzip logs.
|
|
159
|
+
- Service exposure inventory support.
|
|
160
|
+
- Reachability evidence from source-code symbol search.
|
|
161
|
+
- Explicit OSV advisory import.
|
|
162
|
+
- JSON, JSONL, Markdown, SARIF, and terminal output.
|
|
163
|
+
- Interactive command shell with profiles, history, completions, modules, and exports.
|
|
164
|
+
- Cross-platform CI for Node 20 and 22 on Linux, macOS, and Windows.
|
|
165
|
+
|
|
166
|
+
What is still evolving:
|
|
167
|
+
|
|
168
|
+
- OSV multi-affected and multi-range normalization.
|
|
169
|
+
- NVD and CISA KEV import.
|
|
170
|
+
- Deeper SBOM support.
|
|
171
|
+
- Docker image and Kubernetes exposure analysis.
|
|
172
|
+
- Full YARA and Sigma engines.
|
|
173
|
+
- More precise reachability analysis.
|
|
174
|
+
|
|
175
|
+
## Design Goals
|
|
176
|
+
|
|
177
|
+
- Local-first by default.
|
|
178
|
+
- Evidence over opaque risk scores.
|
|
179
|
+
- Small enough to inspect.
|
|
180
|
+
- Useful in terminals, scripts, tickets, and CI jobs.
|
|
181
|
+
- Honest about uncertainty and limitations.
|
|
182
|
+
|
|
183
|
+
## Quick Start
|
|
184
|
+
|
|
185
|
+
Install from npm:
|
|
186
|
+
|
|
187
|
+
```bash
|
|
188
|
+
npm install -g relsec
|
|
189
|
+
relevant --version
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
Run the bundled example after cloning the repository:
|
|
193
|
+
|
|
194
|
+
```bash
|
|
195
|
+
npm install
|
|
196
|
+
npm run build
|
|
197
|
+
node dist/cli.js cve CVE-2026-41001 --workspace examples/enterprise --inventory examples/enterprise/security/inventory.json --format markdown
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
Example output:
|
|
201
|
+
|
|
202
|
+
```txt
|
|
203
|
+
CVE-2026-41001: relevant (critical)
|
|
204
|
+
Multer multipart upload path traversal in file field handling: vulnerable package is reachable from an externally exposed service.
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
## Quick Command Examples
|
|
208
|
+
|
|
209
|
+
Check whether a CVE matters locally:
|
|
210
|
+
|
|
211
|
+
```bash
|
|
212
|
+
npx relsec cve CVE-2026-41001 \
|
|
213
|
+
--workspace examples/enterprise \
|
|
214
|
+
--inventory examples/enterprise/security/inventory.json \
|
|
215
|
+
--format markdown
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
Scan logs for indicators:
|
|
219
|
+
|
|
220
|
+
```bash
|
|
221
|
+
npx relsec ioc \
|
|
222
|
+
--indicators examples/enterprise/security/cisa-aa26-141a.iocs \
|
|
223
|
+
--logs examples/enterprise/security/logs/okta-auth-prod-2026-05-21.log \
|
|
224
|
+
--logs examples/enterprise/security/logs/zscaler-web-prod-2026-05-21.log \
|
|
225
|
+
--format json
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
Open the interactive console:
|
|
229
|
+
|
|
230
|
+
```bash
|
|
231
|
+
npx relsec
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
## Commands
|
|
235
|
+
|
|
236
|
+
```bash
|
|
237
|
+
relevant cve <CVE-ID> --workspace . --inventory security/inventory.json --format json
|
|
238
|
+
relevant ioc --indicators indicators.txt --logs auth.log --logs proxy.log --format json
|
|
239
|
+
relevant import osv --workspace . --inventory security/inventory.json --output security/osv-advisories.json
|
|
240
|
+
relevant advisories
|
|
241
|
+
relevant version
|
|
242
|
+
relevant
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
Output formats:
|
|
246
|
+
|
|
247
|
+
- `text`
|
|
248
|
+
- `json`
|
|
249
|
+
- `jsonl`
|
|
250
|
+
- `markdown`
|
|
251
|
+
- `sarif`
|
|
252
|
+
|
|
253
|
+
## Interactive Console
|
|
254
|
+
|
|
255
|
+
Run `relevant` with no arguments to open a REPL-style command shell. It keeps session context, supports command history, profiles, named workspaces, path completion, and module-style workflows.
|
|
256
|
+
|
|
257
|
+
```txt
|
|
258
|
+
rel > set workspace examples/enterprise
|
|
259
|
+
rel > set inventory examples/enterprise/security/inventory.json
|
|
260
|
+
rel > scan CVE-2026-41001
|
|
261
|
+
rel > evidence
|
|
262
|
+
rel > actions
|
|
263
|
+
rel > export markdown finding.md
|
|
264
|
+
rel > set indicators examples/enterprise/security/cisa-aa26-141a.iocs
|
|
265
|
+
rel > ioc examples/enterprise/security/logs/okta-auth-prod-2026-05-21.log
|
|
266
|
+
rel > exit
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
Module workflow:
|
|
270
|
+
|
|
271
|
+
```txt
|
|
272
|
+
rel > use cve
|
|
273
|
+
rel(cve) > set cve CVE-2026-41001
|
|
274
|
+
rel(cve) > show options
|
|
275
|
+
rel(cve) > run
|
|
276
|
+
rel(cve) > back
|
|
277
|
+
rel > show modules
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
Available modules:
|
|
281
|
+
|
|
282
|
+
- `cve`: dependency CVE relevance
|
|
283
|
+
- `ioc`: IOC log matching
|
|
284
|
+
- `exposure`: externally exposed services
|
|
285
|
+
- `sbom`: dependency inventory
|
|
286
|
+
- `secrets`: obvious local secret patterns
|
|
287
|
+
- `cloudtrail`: CloudTrail triage heuristics
|
|
288
|
+
- `auth`: identity/auth log triage heuristics
|
|
289
|
+
- `yara`: simple YARA literal rules
|
|
290
|
+
- `sigma`: simple Sigma keyword rules
|
|
291
|
+
|
|
292
|
+
## Example Environment
|
|
293
|
+
|
|
294
|
+
`examples/enterprise` is a dummy environment for testing and demos:
|
|
295
|
+
|
|
296
|
+
- `checkout-api`: internet-facing Node service with vulnerable reachable `multer` upload usage.
|
|
297
|
+
- `ml-worker`: internal Python worker with a vulnerable package version but no vulnerable parser reachability.
|
|
298
|
+
- Okta, Zscaler, and AWS CloudTrail-style logs.
|
|
299
|
+
- CISA-style IOC list.
|
|
300
|
+
- Service exposure inventory.
|
|
301
|
+
|
|
302
|
+
No real customer data is included.
|
|
303
|
+
|
|
304
|
+
## Privacy Model
|
|
305
|
+
|
|
306
|
+
Normal scans are local-first:
|
|
307
|
+
|
|
308
|
+
- CVE analysis reads local manifests, inventories, source files, SBOMs, and advisory files.
|
|
309
|
+
- IOC analysis reads local logs directly.
|
|
310
|
+
- Reports are written locally.
|
|
311
|
+
- No telemetry is collected.
|
|
312
|
+
- No cloud API is used during normal scans.
|
|
313
|
+
|
|
314
|
+
The `import osv` command is the one intentional networked workflow. It sends discovered package names, ecosystems, and versions to the configured OSV API endpoint, then writes normalized advisory records to a local file for later offline use.
|
|
315
|
+
|
|
316
|
+
## Limitations
|
|
317
|
+
|
|
318
|
+
This is an alpha project with deliberate constraints:
|
|
319
|
+
|
|
320
|
+
- CVE relevance depends on advisory quality, manifest coverage, inventory accuracy, and symbol search.
|
|
321
|
+
- Reachability is currently evidence-oriented string matching, not full program analysis.
|
|
322
|
+
- OSV import does not yet preserve every multi-affected or multi-range advisory shape.
|
|
323
|
+
- YARA support handles literal string rules, not the full YARA language.
|
|
324
|
+
- Sigma support handles simple keyword-style rules, not a full Sigma backend.
|
|
325
|
+
- CloudTrail and auth modules are deterministic triage heuristics, not SIEM replacements.
|
|
326
|
+
- Secret detection is heuristic and should not replace dedicated secret scanning.
|
|
327
|
+
- Generated reports may contain sensitive local evidence.
|
|
328
|
+
|
|
329
|
+
## Development
|
|
330
|
+
|
|
331
|
+
```bash
|
|
332
|
+
npm install
|
|
333
|
+
npm run typecheck
|
|
334
|
+
npm test
|
|
335
|
+
npm run build
|
|
336
|
+
```
|
|
337
|
+
|
|
338
|
+
Full local release gate:
|
|
339
|
+
|
|
340
|
+
```bash
|
|
341
|
+
npm run release:check
|
|
342
|
+
npm run pack:dry-run
|
|
343
|
+
```
|
|
344
|
+
|
|
345
|
+
CI runs typecheck, tests, build, and package dry-run on Node 20 and 22 across Linux, macOS, and Windows.
|
|
346
|
+
|
|
347
|
+
## Contributing
|
|
348
|
+
|
|
349
|
+
Contributions are welcome. Good first areas:
|
|
350
|
+
|
|
351
|
+
- More fixture environments.
|
|
352
|
+
- Additional advisory import formats.
|
|
353
|
+
- Better SBOM parsing.
|
|
354
|
+
- More report templates.
|
|
355
|
+
- Safer scanner heuristics.
|
|
356
|
+
- Documentation and examples.
|
|
357
|
+
|
|
358
|
+
Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.
|
|
359
|
+
|
|
360
|
+
## Roadmap
|
|
361
|
+
|
|
362
|
+
- Preserve OSV multi-affected and multi-range records.
|
|
363
|
+
- Add NVD and CISA KEV import.
|
|
364
|
+
- Expand CycloneDX and SPDX support.
|
|
365
|
+
- Add Docker image and Kubernetes manifest exposure analysis.
|
|
366
|
+
- Add GitHub and Jira export templates.
|
|
367
|
+
- Add optional local summarization through Ollama or LM Studio.
|
|
368
|
+
- Improve reachability analysis while keeping the tool local-first.
|
|
369
|
+
|
|
370
|
+
## Security
|
|
371
|
+
|
|
372
|
+
See [SECURITY.md](SECURITY.md) for the security model, network behavior, sensitive data guidance, and vulnerability reporting notes.
|
|
373
|
+
|
|
374
|
+
## License
|
|
375
|
+
|
|
376
|
+
MIT. See [LICENSE](LICENSE).
|
package/SECURITY.md
ADDED
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# Security and Privacy
|
|
2
|
+
|
|
3
|
+
`relevant` is designed as a local-first security relevance CLI.
|
|
4
|
+
|
|
5
|
+
## Local-First Behavior
|
|
6
|
+
|
|
7
|
+
- CVE relevance analysis runs against local manifests, inventory files, source files, SBOMs, and logs.
|
|
8
|
+
- IOC scans read local log files directly.
|
|
9
|
+
- No telemetry is collected.
|
|
10
|
+
- No project files, logs, indicators, or results are uploaded by default.
|
|
11
|
+
|
|
12
|
+
## Network Access
|
|
13
|
+
|
|
14
|
+
The current CLI does not make network requests during normal scans.
|
|
15
|
+
|
|
16
|
+
The `import osv` command fetches public advisory data from OSV only when explicitly requested by the user. It sends discovered package names, ecosystems, and versions to the configured OSV API endpoint and writes the normalized advisory records to a local file for later offline scans.
|
|
17
|
+
|
|
18
|
+
Future advisory import commands must document the target source and the identifiers being requested before they are enabled by default.
|
|
19
|
+
|
|
20
|
+
## Sensitive Data
|
|
21
|
+
|
|
22
|
+
The tool may process sensitive local logs, secrets, inventories, and source code. Treat generated reports as sensitive unless reviewed.
|
|
23
|
+
|
|
24
|
+
The `secrets` module redacts obvious secret values in output, but it is heuristic and not a substitute for a dedicated secret-scanning product.
|
|
25
|
+
|
|
26
|
+
## Detector Limitations
|
|
27
|
+
|
|
28
|
+
- CVE relevance depends on available advisory data, manifest coverage, inventory accuracy, and simple symbol reachability.
|
|
29
|
+
- YARA support currently handles literal string rules. It is not a full YARA engine.
|
|
30
|
+
- Sigma support currently handles simple keyword-style rules. It is not a full Sigma backend.
|
|
31
|
+
- CloudTrail and auth modules use deterministic heuristics for local triage.
|
|
32
|
+
- False positives and false negatives are expected.
|
|
33
|
+
|
|
34
|
+
## Reporting Vulnerabilities
|
|
35
|
+
|
|
36
|
+
Before public release, use private issue reporting in the repository or contact the maintainer directly. Do not publish exploit details until a fix is available.
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
import type { AdvisoryRecord } from './types.js';
|
|
2
|
+
export declare function findAdvisory(id: string, extraAdvisories?: AdvisoryRecord[]): AdvisoryRecord | undefined;
|
|
3
|
+
export declare function listAdvisories(): AdvisoryRecord[];
|
|
4
|
+
export declare function loadAdvisoriesFromFile(filePath: string): Promise<AdvisoryRecord[]>;
|
|
5
|
+
export declare function normalizeAdvisory(value: unknown): AdvisoryRecord;
|
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
import { readFile } from 'node:fs/promises';
|
|
2
|
+
const ADVISORIES = [
|
|
3
|
+
{
|
|
4
|
+
id: 'CVE-2026-41001',
|
|
5
|
+
title: 'Multer multipart upload path traversal in file field handling',
|
|
6
|
+
ecosystem: 'npm',
|
|
7
|
+
packageName: 'multer',
|
|
8
|
+
vulnerableRange: '<1.4.5-lts.1',
|
|
9
|
+
fixedVersion: '1.4.5-lts.1',
|
|
10
|
+
vulnerableSymbols: ['upload.single', 'upload.array', 'multer('],
|
|
11
|
+
summary: 'Malformed multipart uploads may write attacker-controlled files when vulnerable Multer handlers are reachable.',
|
|
12
|
+
recommendedActions: [
|
|
13
|
+
'Upgrade multer to >=1.4.5-lts.1.',
|
|
14
|
+
'Restrict public upload endpoints until patched.',
|
|
15
|
+
'Search access logs for unusual multipart upload paths.'
|
|
16
|
+
]
|
|
17
|
+
},
|
|
18
|
+
{
|
|
19
|
+
id: 'CVE-2026-41002',
|
|
20
|
+
title: 'Pillow image decoder heap overflow in unsafe parser path',
|
|
21
|
+
ecosystem: 'pypi',
|
|
22
|
+
packageName: 'pillow',
|
|
23
|
+
vulnerableRange: '<10.2.0',
|
|
24
|
+
fixedVersion: '10.2.0',
|
|
25
|
+
vulnerableSymbols: ['ImageFile.Parser', 'features.pilinfo', 'UnsafeImageDecode'],
|
|
26
|
+
summary: 'Specific Pillow parser APIs may crash or corrupt memory when processing hostile images.',
|
|
27
|
+
recommendedActions: [
|
|
28
|
+
'Upgrade pillow to >=10.2.0.',
|
|
29
|
+
'Confirm whether vulnerable parser APIs are reachable from untrusted input.',
|
|
30
|
+
'Keep image processing workers isolated from production credentials.'
|
|
31
|
+
]
|
|
32
|
+
}
|
|
33
|
+
];
|
|
34
|
+
export function findAdvisory(id, extraAdvisories = []) {
|
|
35
|
+
return [...extraAdvisories, ...ADVISORIES].find((record) => record.id.toLowerCase() === id.toLowerCase());
|
|
36
|
+
}
|
|
37
|
+
export function listAdvisories() {
|
|
38
|
+
return [...ADVISORIES];
|
|
39
|
+
}
|
|
40
|
+
export async function loadAdvisoriesFromFile(filePath) {
|
|
41
|
+
const parsed = JSON.parse(await readFile(filePath, 'utf8'));
|
|
42
|
+
const records = Array.isArray(parsed) ? parsed : [parsed];
|
|
43
|
+
return records.map(normalizeAdvisory);
|
|
44
|
+
}
|
|
45
|
+
export function normalizeAdvisory(value) {
|
|
46
|
+
if (!isRecord(value))
|
|
47
|
+
throw new Error('Invalid advisory record');
|
|
48
|
+
if (typeof value.id !== 'string')
|
|
49
|
+
throw new Error('Advisory id is required');
|
|
50
|
+
if (Array.isArray(value.affected))
|
|
51
|
+
return normalizeOsv(value);
|
|
52
|
+
const ecosystem = value.ecosystem === 'pypi' ? 'pypi' : 'npm';
|
|
53
|
+
if (typeof value.packageName !== 'string')
|
|
54
|
+
throw new Error('Advisory packageName is required');
|
|
55
|
+
return {
|
|
56
|
+
id: value.id,
|
|
57
|
+
title: stringValue(value.title) ?? stringValue(value.summary) ?? value.id,
|
|
58
|
+
ecosystem,
|
|
59
|
+
packageName: value.packageName,
|
|
60
|
+
vulnerableRange: stringValue(value.vulnerableRange) ?? '<999999.0.0',
|
|
61
|
+
fixedVersion: stringValue(value.fixedVersion),
|
|
62
|
+
vulnerableSymbols: stringArray(value.vulnerableSymbols),
|
|
63
|
+
summary: stringValue(value.summary) ?? value.id,
|
|
64
|
+
recommendedActions: stringArray(value.recommendedActions, ['Review the imported advisory and patch affected services.'])
|
|
65
|
+
};
|
|
66
|
+
}
|
|
67
|
+
function normalizeOsv(value) {
|
|
68
|
+
const affectedList = Array.isArray(value.affected) ? value.affected : [];
|
|
69
|
+
const affected = affectedList[0];
|
|
70
|
+
if (!isRecord(affected))
|
|
71
|
+
throw new Error('OSV advisory affected package is required');
|
|
72
|
+
const packageInfo = affected.package;
|
|
73
|
+
if (!isRecord(packageInfo) || typeof packageInfo.name !== 'string')
|
|
74
|
+
throw new Error('OSV package name is required');
|
|
75
|
+
const ecosystem = String(packageInfo.ecosystem ?? '').toLowerCase() === 'pypi' ? 'pypi' : 'npm';
|
|
76
|
+
const fixedVersion = osvFixedVersion(affected);
|
|
77
|
+
const ecosystemSpecific = affected.ecosystem_specific;
|
|
78
|
+
return {
|
|
79
|
+
id: value.id,
|
|
80
|
+
title: stringValue(value.summary) ?? value.id,
|
|
81
|
+
ecosystem,
|
|
82
|
+
packageName: packageInfo.name,
|
|
83
|
+
vulnerableRange: fixedVersion ? `<${fixedVersion}` : '<999999.0.0',
|
|
84
|
+
fixedVersion,
|
|
85
|
+
vulnerableSymbols: isRecord(ecosystemSpecific) ? stringArray(ecosystemSpecific.vulnerable_symbols) : [],
|
|
86
|
+
summary: stringValue(value.details) ?? stringValue(value.summary) ?? value.id,
|
|
87
|
+
recommendedActions: fixedVersion ? [`Upgrade ${packageInfo.name} to >=${fixedVersion}.`] : [`Review advisory ${value.id}.`]
|
|
88
|
+
};
|
|
89
|
+
}
|
|
90
|
+
function osvFixedVersion(affected) {
|
|
91
|
+
const ranges = Array.isArray(affected.ranges) ? affected.ranges : [];
|
|
92
|
+
for (const range of ranges) {
|
|
93
|
+
if (!isRecord(range) || !Array.isArray(range.events))
|
|
94
|
+
continue;
|
|
95
|
+
for (const event of range.events) {
|
|
96
|
+
if (isRecord(event) && typeof event.fixed === 'string')
|
|
97
|
+
return event.fixed;
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
return undefined;
|
|
101
|
+
}
|
|
102
|
+
function stringValue(value) {
|
|
103
|
+
return typeof value === 'string' ? value : undefined;
|
|
104
|
+
}
|
|
105
|
+
function stringArray(value, fallback = []) {
|
|
106
|
+
return Array.isArray(value) ? value.filter((item) => typeof item === 'string') : fallback;
|
|
107
|
+
}
|
|
108
|
+
function isRecord(value) {
|
|
109
|
+
return typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
110
|
+
}
|
|
111
|
+
//# sourceMappingURL=advisories.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"advisories.js","sourceRoot":"","sources":["../src/advisories.ts"],"names":[],"mappings":"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"}
|
package/dist/cli.d.ts
ADDED