@thorcollective/hearth-mcp 0.0.0-stage → 0.0.1
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 +134 -2
- package/data/actor-mentions.json +198 -0
- package/data/context-graph-data.json +35522 -0
- package/data/datasource-mapping.json +1845 -0
- package/data/hunts-data.json +24273 -0
- package/data/mitre-matrix.json +12105 -0
- package/dist/index.js +1033 -0
- package/package.json +51 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2024 THOR Collective
|
|
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,135 @@
|
|
|
1
|
-
#
|
|
1
|
+
# HEARTH MCP server
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Ask your AI assistant what to hunt for. This [MCP](https://modelcontextprotocol.io) server gives Claude, Cursor, VS Code and other MCP clients read-only access to [HEARTH](https://hearth.thorcollective.com), the community library of threat hunting hypotheses.
|
|
4
|
+
|
|
5
|
+
Questions you can ask:
|
|
6
|
+
|
|
7
|
+
- "What can I hunt for Volt Typhoon with firewall and appliance logs?"
|
|
8
|
+
- "Find hunts for macOS persistence."
|
|
9
|
+
- "We only have Windows endpoint and identity logs. Which hunts can we run fully?"
|
|
10
|
+
- "Show me H432."
|
|
11
|
+
|
|
12
|
+
## Tools
|
|
13
|
+
|
|
14
|
+
| Tool | What it does |
|
|
15
|
+
| ----------------------- | --------------------------------------------------------------------------------------- |
|
|
16
|
+
| `search_hunts` | Ranked keyword search, with filters for category, tactic and data sources. |
|
|
17
|
+
| `get_hunt` | One hunt in full: hypothesis, why it matters, notes, queries and references. |
|
|
18
|
+
| `hunts_for_actor` | Hunts for a threat actor by name, alias or ATT&CK group ID. Includes coverage and gaps. |
|
|
19
|
+
| `hunts_for_datasources` | Hunts your team can run with the log sources it has, and what each one is missing. |
|
|
20
|
+
|
|
21
|
+
Every tool is read-only. Retired hunts are hidden unless you ask for them.
|
|
22
|
+
|
|
23
|
+
## Install
|
|
24
|
+
|
|
25
|
+
You need Node.js 20 or later. Each snippet runs the published package with `npx`.
|
|
26
|
+
|
|
27
|
+
### Claude Code
|
|
28
|
+
|
|
29
|
+
```sh
|
|
30
|
+
claude mcp add hearth -- npx -y @thorcollective/hearth-mcp
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
### Claude Desktop
|
|
34
|
+
|
|
35
|
+
Add this to `claude_desktop_config.json` (**Settings → Developer → Edit Config**), then restart Claude Desktop:
|
|
36
|
+
|
|
37
|
+
```json
|
|
38
|
+
{
|
|
39
|
+
"mcpServers": {
|
|
40
|
+
"hearth": {
|
|
41
|
+
"command": "npx",
|
|
42
|
+
"args": ["-y", "@thorcollective/hearth-mcp"]
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
### Cursor
|
|
49
|
+
|
|
50
|
+
Add this to `.cursor/mcp.json` in your project, or to `~/.cursor/mcp.json` for every project:
|
|
51
|
+
|
|
52
|
+
```json
|
|
53
|
+
{
|
|
54
|
+
"mcpServers": {
|
|
55
|
+
"hearth": {
|
|
56
|
+
"command": "npx",
|
|
57
|
+
"args": ["-y", "@thorcollective/hearth-mcp"]
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
### VS Code
|
|
64
|
+
|
|
65
|
+
Add this to `.vscode/mcp.json` in your workspace:
|
|
66
|
+
|
|
67
|
+
```json
|
|
68
|
+
{
|
|
69
|
+
"servers": {
|
|
70
|
+
"hearth": {
|
|
71
|
+
"type": "stdio",
|
|
72
|
+
"command": "npx",
|
|
73
|
+
"args": ["-y", "@thorcollective/hearth-mcp"]
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
### Settings
|
|
80
|
+
|
|
81
|
+
| Environment variable | Effect |
|
|
82
|
+
|---|---|
|
|
83
|
+
| `HEARTH_OFFLINE=1` | Never touch the network; serve the bundled snapshot or the last download. |
|
|
84
|
+
| `HEARTH_DATA_URL` | Fetch data from a mirror instead of `https://hearth.thorcollective.com/`. Must be https (http only for localhost). |
|
|
85
|
+
| `HEARTH_CACHE_DIR` | Where downloaded data is kept. Defaults to your platform's cache folder (`~/Library/Caches/hearth-mcp` on macOS). |
|
|
86
|
+
|
|
87
|
+
Set them in your client's config, for example `"env": { "HEARTH_OFFLINE": "1" }` next to `"args"`.
|
|
88
|
+
|
|
89
|
+
### Other clients
|
|
90
|
+
|
|
91
|
+
Any MCP client that supports stdio servers can run the same command: `npx -y @thorcollective/hearth-mcp`.
|
|
92
|
+
|
|
93
|
+
## Privacy and security
|
|
94
|
+
|
|
95
|
+
- **No telemetry.** The server sends nothing anywhere.
|
|
96
|
+
- **One small network check a day.** At most once every 24 hours the server asks hearth.thorcollective.com whether the hunt data has changed. It uses conditional requests, so usually nothing is downloaded. It sends only those requests and a `hearth-mcp/<version>` user agent.
|
|
97
|
+
- **Works offline.** If the site can't be reached, or sends data that fails validation, the server keeps using its last good copy, falling back to the snapshot bundled with each release.
|
|
98
|
+
- **Hunt text is treated as untrusted.** Hunts are written by the community:
|
|
99
|
+
- The server makes hidden and right-to-left characters visible, and removes hidden text.
|
|
100
|
+
- It caps field lengths.
|
|
101
|
+
- It labels every hunt text field as untrusted, so your assistant reads it as data, not instructions.
|
|
102
|
+
- New hunts are also checked for prompt-injection text in CI before they merge.
|
|
103
|
+
- **Review detection queries before you run them**, as you would any query from the internet.
|
|
104
|
+
- **Verify the package:** releases are published from GitHub Actions with [npm provenance](https://docs.npmjs.com/generating-provenance-statements). Run `npm audit signatures` after installing to check it.
|
|
105
|
+
|
|
106
|
+
## Develop
|
|
107
|
+
|
|
108
|
+
From the repository root:
|
|
109
|
+
|
|
110
|
+
```sh
|
|
111
|
+
npm ci && npm ci --prefix mcp
|
|
112
|
+
npm run build --prefix mcp # bundle to mcp/dist and snapshot site data to mcp/data
|
|
113
|
+
npm test # unit, golden and stdio protocol tests
|
|
114
|
+
claude mcp add hearth-dev -- node "$PWD/mcp/dist/index.js"
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
The server reuses the site's own logic from `src/lib`, so search behaves the same way in both.
|
|
118
|
+
|
|
119
|
+
### Golden queries
|
|
120
|
+
|
|
121
|
+
`mcp/golden/` holds real analyst questions and the hunts a good answer must include. Adding one is the most useful way to improve search. See [`golden/README.md`](golden/README.md).
|
|
122
|
+
|
|
123
|
+
## Releasing
|
|
124
|
+
|
|
125
|
+
Maintainers only:
|
|
126
|
+
|
|
127
|
+
1. Bump `version` in `mcp/package.json` and `mcp/server.json`. A test fails if they differ.
|
|
128
|
+
2. Merge to `main`.
|
|
129
|
+
3. Push a tag named `mcp-v<version>`, for example `mcp-v0.1.0`.
|
|
130
|
+
|
|
131
|
+
The [publish workflow](../.github/workflows/publish-mcp.yml) then:
|
|
132
|
+
|
|
133
|
+
1. Waits for approval in the `npm-publish` environment.
|
|
134
|
+
2. Publishes to npm with provenance, using trusted publishing (no npm token is stored).
|
|
135
|
+
3. Lists the release in the [MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.THORCollective/hearth`.
|
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
{
|
|
2
|
+
"mentions": {
|
|
3
|
+
"actor:G0004": [
|
|
4
|
+
"H325",
|
|
5
|
+
"H326"
|
|
6
|
+
],
|
|
7
|
+
"actor:G0007": [
|
|
8
|
+
"B005",
|
|
9
|
+
"B015",
|
|
10
|
+
"H078",
|
|
11
|
+
"H083",
|
|
12
|
+
"H116",
|
|
13
|
+
"M029"
|
|
14
|
+
],
|
|
15
|
+
"actor:G0010": [
|
|
16
|
+
"B028"
|
|
17
|
+
],
|
|
18
|
+
"actor:G0016": [
|
|
19
|
+
"B005",
|
|
20
|
+
"B040",
|
|
21
|
+
"H122",
|
|
22
|
+
"H159",
|
|
23
|
+
"H167",
|
|
24
|
+
"H169",
|
|
25
|
+
"M036"
|
|
26
|
+
],
|
|
27
|
+
"actor:G0032": [
|
|
28
|
+
"B005"
|
|
29
|
+
],
|
|
30
|
+
"actor:G0035": [
|
|
31
|
+
"H235"
|
|
32
|
+
],
|
|
33
|
+
"actor:G0044": [
|
|
34
|
+
"H011"
|
|
35
|
+
],
|
|
36
|
+
"actor:G0050": [
|
|
37
|
+
"B024",
|
|
38
|
+
"H150",
|
|
39
|
+
"H187",
|
|
40
|
+
"M019"
|
|
41
|
+
],
|
|
42
|
+
"actor:G0059": [
|
|
43
|
+
"H060"
|
|
44
|
+
],
|
|
45
|
+
"actor:G0067": [
|
|
46
|
+
"H084",
|
|
47
|
+
"H410"
|
|
48
|
+
],
|
|
49
|
+
"actor:G0073": [
|
|
50
|
+
"M005"
|
|
51
|
+
],
|
|
52
|
+
"actor:G0082": [
|
|
53
|
+
"H020",
|
|
54
|
+
"H023",
|
|
55
|
+
"H027",
|
|
56
|
+
"H028",
|
|
57
|
+
"H029",
|
|
58
|
+
"H030",
|
|
59
|
+
"H031",
|
|
60
|
+
"H032",
|
|
61
|
+
"H054",
|
|
62
|
+
"H130",
|
|
63
|
+
"H131",
|
|
64
|
+
"H132",
|
|
65
|
+
"H133",
|
|
66
|
+
"H136",
|
|
67
|
+
"H199",
|
|
68
|
+
"H382",
|
|
69
|
+
"M004"
|
|
70
|
+
],
|
|
71
|
+
"actor:G0094": [
|
|
72
|
+
"B006",
|
|
73
|
+
"B040",
|
|
74
|
+
"B050",
|
|
75
|
+
"H160",
|
|
76
|
+
"H275",
|
|
77
|
+
"H276",
|
|
78
|
+
"M036"
|
|
79
|
+
],
|
|
80
|
+
"actor:G0096": [
|
|
81
|
+
"H011",
|
|
82
|
+
"H085",
|
|
83
|
+
"H421"
|
|
84
|
+
],
|
|
85
|
+
"actor:G0102": [
|
|
86
|
+
"H008",
|
|
87
|
+
"M005"
|
|
88
|
+
],
|
|
89
|
+
"actor:G0117": [
|
|
90
|
+
"M005"
|
|
91
|
+
],
|
|
92
|
+
"actor:G0125": [
|
|
93
|
+
"B015",
|
|
94
|
+
"B050",
|
|
95
|
+
"H116",
|
|
96
|
+
"H159"
|
|
97
|
+
],
|
|
98
|
+
"actor:G0134": [
|
|
99
|
+
"H093"
|
|
100
|
+
],
|
|
101
|
+
"actor:G0138": [
|
|
102
|
+
"H439"
|
|
103
|
+
],
|
|
104
|
+
"actor:G1004": [
|
|
105
|
+
"B007"
|
|
106
|
+
],
|
|
107
|
+
"actor:G1006": [
|
|
108
|
+
"B069",
|
|
109
|
+
"H304",
|
|
110
|
+
"H305",
|
|
111
|
+
"H331",
|
|
112
|
+
"H427",
|
|
113
|
+
"H453",
|
|
114
|
+
"H455",
|
|
115
|
+
"M062"
|
|
116
|
+
],
|
|
117
|
+
"actor:G1015": [
|
|
118
|
+
"H065",
|
|
119
|
+
"H376"
|
|
120
|
+
],
|
|
121
|
+
"actor:G1017": [
|
|
122
|
+
"H432"
|
|
123
|
+
],
|
|
124
|
+
"actor:G1022": [
|
|
125
|
+
"H216"
|
|
126
|
+
],
|
|
127
|
+
"actor:G1024": [
|
|
128
|
+
"B014",
|
|
129
|
+
"B015",
|
|
130
|
+
"B019",
|
|
131
|
+
"B029",
|
|
132
|
+
"H047",
|
|
133
|
+
"H058",
|
|
134
|
+
"H114",
|
|
135
|
+
"H115",
|
|
136
|
+
"H116",
|
|
137
|
+
"H117",
|
|
138
|
+
"H214",
|
|
139
|
+
"H215",
|
|
140
|
+
"H361",
|
|
141
|
+
"M015",
|
|
142
|
+
"M024"
|
|
143
|
+
],
|
|
144
|
+
"actor:G1032": [
|
|
145
|
+
"H349",
|
|
146
|
+
"H350",
|
|
147
|
+
"M051"
|
|
148
|
+
],
|
|
149
|
+
"actor:G1033": [
|
|
150
|
+
"H362",
|
|
151
|
+
"H363"
|
|
152
|
+
],
|
|
153
|
+
"actor:G1037": [
|
|
154
|
+
"H245"
|
|
155
|
+
],
|
|
156
|
+
"actor:G1040": [
|
|
157
|
+
"B019",
|
|
158
|
+
"H289",
|
|
159
|
+
"H318"
|
|
160
|
+
],
|
|
161
|
+
"actor:G1043": [
|
|
162
|
+
"H376"
|
|
163
|
+
],
|
|
164
|
+
"actor:G1046": [
|
|
165
|
+
"H118"
|
|
166
|
+
],
|
|
167
|
+
"actor:G1052": [
|
|
168
|
+
"H236"
|
|
169
|
+
],
|
|
170
|
+
"actor:G1053": [
|
|
171
|
+
"H163",
|
|
172
|
+
"H273"
|
|
173
|
+
],
|
|
174
|
+
"actor:G1056": [
|
|
175
|
+
"H103",
|
|
176
|
+
"H351"
|
|
177
|
+
],
|
|
178
|
+
"actor:G1057": [
|
|
179
|
+
"H190",
|
|
180
|
+
"H191",
|
|
181
|
+
"H192",
|
|
182
|
+
"H234",
|
|
183
|
+
"H329",
|
|
184
|
+
"H365",
|
|
185
|
+
"M028"
|
|
186
|
+
],
|
|
187
|
+
"actor:G1058": [
|
|
188
|
+
"B019",
|
|
189
|
+
"B026",
|
|
190
|
+
"B030",
|
|
191
|
+
"H170",
|
|
192
|
+
"H324",
|
|
193
|
+
"H458",
|
|
194
|
+
"H459"
|
|
195
|
+
]
|
|
196
|
+
},
|
|
197
|
+
"min_alias_len": 4
|
|
198
|
+
}
|