forked from OALabs/hashdb-bn
-
Notifications
You must be signed in to change notification settings - Fork 4
/
hashdb_api.py
349 lines (288 loc) · 11.3 KB
/
hashdb_api.py
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
"""
Module for interacting with the HashDB API.
This module performs requests against the API, and provides types representing hash lookup results deserialized from the data returned by the API.
The module can interact with the original service at hashdb.openanalysis.net, or can interact with any other HashDB service instance which conforms to the OpenAPI specification at https://hashdb.openanalysis.net/openapi.json.
"""
import asyncio
from dataclasses import dataclass
from typing import Any, Dict, List, Optional, Union
from urllib.parse import urljoin
import binaryninja
import httpx
logger = binaryninja.log.Logger(session_id=0, logger_name=__name__)
class HashDBError(Exception):
pass
@dataclass
class AlgorithmType:
"""
Represents the data type and data size, in bytes, of the values produced by a specific hash algorithm.
"""
name: str
size: int
@classmethod
def from_raw_name(cls, raw_name: str):
if raw_name == "unsigned_int":
return cls(
name="unsigned_int",
size=4,
)
elif raw_name == "unsigned_long":
return cls(
name="unsigned_long",
size=8,
)
else:
raise KeyError("Could not parse unknown algorithm type {raw_name}")
def __str__(self) -> str:
return f"{self.name} ({self.size} bytes)"
@dataclass
class Algorithm:
"""
Represents the type `components/schemas/algorithm` in the HashDB OpenAPI specification.
For example, `GET /hash/{algorithm}` returns an instance of this type of object.
"""
algorithm: str
description: str
type: AlgorithmType
@classmethod
def from_dict(cls, src: Dict[str, Any]):
result = cls(
algorithm=src["algorithm"],
description=src["description"],
type=AlgorithmType.from_raw_name(src["type"]),
)
return result
def __str__(self) -> str:
return f"{self.algorithm} [{self.type}]: {self.description}"
@dataclass
class HashString:
"""
Represents the type `components/schemas/string` in the HashDB OpenAPI specification.
For example, `GET /string/{string}` returns an instance of this type of object.
"""
string: str
is_api: bool
permutation: Optional[str]
api: Optional[str]
modules: Optional[List[str]]
@classmethod
def from_dict(cls, src: Dict[str, Any]):
result = cls(
string=src["string"],
is_api=src["is_api"],
permutation=src.get("permutation"),
api=src.get("api"),
modules=src.get("modules"),
)
return result
def get_api_string_if_available(self) -> str:
if self.is_api and self.api is not None:
return self.api
else:
return self.string
def __str__(self) -> str:
return f"{self.string}"
@dataclass
class Hash:
"""
Represents the type `components/schemas/hash` in the HashDB OpenAPI specification.
For example, `GET /hash/{algorithm}/{hash}` returns an array containing this type of object.
"""
value: int
hash_string: HashString
@classmethod
def from_dict(cls, src: Dict[str, Any]):
result = cls(
value=src["hash"],
hash_string=HashString.from_dict(src["string"]),
)
return result
def __str__(self) -> str:
return f"{self.hash_string}: {self.value:#x}"
@dataclass
class HuntMatch:
"""
Represents the type `components/schemas/hit` in the HashDB OpenAPI specification.
For example, `POST /hunt` returns an array containing this type of object.
"""
algorithm: str
count: int
hitrate: int
@classmethod
def from_dict(cls, src: Dict[str, Any]):
result = cls(
algorithm=src["algorithm"],
count=src["count"],
hitrate=src["hitrate"],
)
return result
TIMEOUT = httpx.Timeout(15, connect=3)
def get_algorithms(api_url: str) -> List[Algorithm]:
"""
Get a list of all hash algorithms known to this HashDB instance.
Results are sorted by algorithm name.
"""
request_url = urljoin(api_url, "/hash")
logger.log_debug(f"get_algorithms requested URL: {request_url}")
try:
r = httpx.get(request_url, timeout=TIMEOUT)
except httpx.RequestError as connection_err:
raise HashDBError(
f"Get algorithm API request failed for URL {request_url} with a network error: {connection_err}"
)
if not r.is_success:
raise HashDBError(
f"Get algorithm API request failed for URL {request_url} with status code {r.status_code}"
)
results = r.json()
logger.log_debug(
f"get_algorithms request to URL: {request_url} returned results\n{results}"
)
try:
algorithms = [
Algorithm.from_dict(algorithm) for algorithm in results["algorithms"]
]
except KeyError as parsing_key_error:
raise HashDBError(
f"Could not parse the following response from URL {request_url} as a valid list of algorithms; parsing failed to find required key {parsing_key_error}:\n{results}"
)
return sorted(algorithms, key=lambda algorithm: algorithm.algorithm)
def get_strings_from_hash(algorithm: str, hash_value: int, api_url: str) -> List[Hash]:
"""
Given an algorithm and a hash value, get the corresponding string which produced the hash.
"""
request_url = urljoin(api_url, f"/hash/{algorithm:s}/{hash_value:d}")
logger.log_debug(f"get_strings_from_hash requested URL: {request_url}")
try:
r = httpx.get(request_url, timeout=TIMEOUT)
except httpx.RequestError as connection_err:
raise HashDBError(
f"Get hash API request failed for URL {request_url} with a network error: {connection_err}"
)
if not r.is_success:
raise HashDBError(
f"Get hash API request failed for URL {request_url} with status code {r.status_code}"
)
results = r.json()
logger.log_debug(
f"get_strings_from_hash request to URL: {request_url} returned results\n{results}"
)
try:
hashes = [Hash.from_dict(hash_) for hash_ in results["hashes"]]
except KeyError as parsing_key_error:
raise HashDBError(
f"Could not parse the following response from URL {request_url} as a valid list of hashes; parsing failed to find required key {parsing_key_error}:\n{results}"
)
return hashes
async def _get_strings_from_hashes_inner(
algorithm: str, hash_values: List[int], api_url: str
) -> List[Union[List[Hash], HashDBError]]:
async def request_task(client, request_url) -> List[Hash]:
logger.log_debug(f"get_strings_from_hashes requested URL: {request_url}")
try:
r = await client.get(request_url, timeout=TIMEOUT)
except httpx.RequestError as connection_err:
raise HashDBError(
f"Get hash API request failed for URL {request_url} with a network error: {connection_err}"
)
if not r.is_success:
raise HashDBError(
f"Get hash API request failed for URL {request_url} with status code {r.status_code}"
)
results = r.json()
logger.log_debug(
f"get_strings_from_hash request to URL: {request_url} returned results\n{results}"
)
try:
hashes = [Hash.from_dict(hash_) for hash_ in results["hashes"]]
except KeyError as parsing_key_error:
raise HashDBError(
f"Could not parse the following response from URL {request_url} as a valid list of hashes; parsing failed to find required key {parsing_key_error}:\n{results}"
)
return hashes
request_urls = [
urljoin(api_url, f"/hash/{algorithm:s}/{hash_value:d}")
for hash_value in hash_values
]
request_tasks = []
async with httpx.AsyncClient() as client:
for request_url in request_urls:
request_tasks.append(
asyncio.ensure_future(request_task(client, request_url))
)
hash_results = await asyncio.gather(*request_tasks, return_exceptions=True)
return hash_results
def get_strings_from_hashes(
algorithm: str, hash_values: List[int], api_url: str
) -> List[Union[List[Hash], HashDBError]]:
"""
Given an algorithm and a list of hash values, get the corresponding strings which produced the hashes.
"""
return asyncio.run(_get_strings_from_hashes_inner(algorithm, hash_values, api_url))
def get_module_hashes(
module_name: str, algorithm: str, permutation: str, api_url: str
) -> List[Hash]:
"""
Given the name of a module (such as a Win32 API library), return a list of the hashes of the names of all APIs which are part of the module.
"""
request_url = urljoin(
api_url, f"/module/{module_name:s}/{algorithm:s}/{permutation:s}"
)
logger.log_debug(f"get_module_hashes requested URL: {request_url}")
try:
r = httpx.get(request_url, timeout=TIMEOUT)
except httpx.RequestError as connection_err:
raise HashDBError(
f"Get hash API request failed for URL {request_url} with a network error: {connection_err}"
)
if not r.is_success:
raise HashDBError(
f"Get hash API request failed for URL {request_url} with status code {r.status_code}"
)
results = r.json()
logger.log_debug(
f"get_module_hashes request to URL: {request_url} returned results\n{results}"
)
try:
hashes = [Hash.from_dict(hash_) for hash_ in results["hashes"]]
except KeyError as parsing_key_error:
raise HashDBError(
f"Could not parse the following response from URL {request_url} as a valid list of hashes; parsing failed to find required key {parsing_key_error}:\n{results}"
)
return hashes
def hunt_hash(hash_value: int, api_url: str) -> List[HuntMatch]:
"""
Given a hash value, get a list of possible hash algorithms which could have produced the hash value.
"""
matches = []
hash_list = [hash_value]
request_url = urljoin(api_url, "/hunt")
request_data = {"hashes": hash_list}
logger.log_debug(
f"hunt_hash requested URL: {request_url} with request data\n{request_data}"
)
try:
r = httpx.post(
request_url,
json=request_data,
timeout=TIMEOUT,
)
except httpx.RequestError as connection_err:
raise HashDBError(
f"Hunt hash API request failed for URL {request_url} with a network error: {connection_err}"
)
if not r.is_success:
raise HashDBError(
f"Hunt hash API request failed for URL {request_url} with status code {r.status_code}, using the following sent request data:\n{request_data}"
)
results = r.json()
logger.log_debug(
f"hunt_hash request to URL: {request_url} returned results\n{results}"
)
try:
matches = [HuntMatch.from_dict(hit) for hit in results["hits"]]
except KeyError as parsing_key_error:
raise HashDBError(
f"Could not parse the following response from URL {request_url} as a valid list of hunt matches; parsing failed to find required key {parsing_key_error}:\n{results}"
)
return sorted(matches, key=lambda match: match.count)