forked from Vector35/binaryninja-api
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathpluginmanager.py
More file actions
409 lines (345 loc) · 13.9 KB
/
pluginmanager.py
File metadata and controls
409 lines (345 loc) · 13.9 KB
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
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
# Copyright (c) 2015-2026 Vector 35 Inc
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
# deal in the Software without restriction, including without limitation the
# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
# sell copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
# IN THE SOFTWARE.
import ctypes
import json
from datetime import datetime, date
from typing import List, Dict, Optional
import binaryninja
from . import _binaryninjacore as core
from . import deprecation
from .enums import PluginType
class RepoPlugin:
"""
``RepoPlugin`` is mostly read-only, however you can install/uninstall enable/disable plugins. RepoPlugins are
created by parsing the plugins.json in a plugin repository.
"""
def __init__(self, handle: 'core.BNRepoPluginHandle'):
self.handle = handle
def __del__(self):
if core is not None:
core.BNFreePlugin(self.handle)
def __repr__(self):
return f"<{self.path} {'installed' if self.installed else 'not-installed'}/{'enabled' if self.enabled else 'disabled'}>"
@property
def path(self) -> str:
"""Relative path from the base of the repository to the actual plugin"""
result = core.BNPluginGetPath(self.handle)
assert result is not None, "core.BNPluginGetPath returned None"
return result
@property
def subdir(self) -> str:
"""Optional sub-directory the plugin code lives in as a relative path from the plugin root"""
result = core.BNPluginGetSubdir(self.handle)
assert result is not None, "core.BNPluginGetSubdir returned None"
return result
@property
def dependencies(self) -> str:
"""Dependencies required for installing this plugin"""
result = core.BNPluginGetDependencies(self.handle)
assert result is not None, "core.BNPluginGetDependencies returned None"
return result
@property
def installed(self) -> bool:
"""Boolean True if the plugin is installed, False otherwise"""
return core.BNPluginIsInstalled(self.handle)
def install(self) -> bool:
"""Attempt to install the given plugin"""
self.install_dependencies()
return core.BNPluginInstall(self.handle)
def uninstall(self) -> bool:
"""Attempt to uninstall the given plugin"""
return core.BNPluginUninstall(self.handle)
@installed.setter
def installed(self, state: bool):
if state:
self.install_dependencies()
core.BNPluginInstall(self.handle)
else:
core.BNPluginUninstall(self.handle)
def install_dependencies(self) -> bool:
return core.BNPluginInstallDependencies(self.handle)
@property
def enabled(self) -> bool:
"""Boolean True if the plugin is currently enabled, False otherwise"""
return core.BNPluginIsEnabled(self.handle)
@enabled.setter
def enabled(self, state: bool):
if state:
core.BNPluginEnable(self.handle, False)
else:
core.BNPluginDisable(self.handle)
def enable(self, force: bool = False) -> bool:
"""
Enable this plugin, optionally trying to force it. \
Force loading a plugin with ignore platform and api constraints. \
(e.g. The plugin author says the plugin will only work on Linux but you'd like to \
attempt to load it on macOS)
"""
return core.BNPluginEnable(self.handle, force)
@property
def api(self) -> List[str]:
"""String indicating the API used by the plugin"""
result: List[str] = []
count = ctypes.c_ulonglong(0)
platforms = core.BNPluginGetApis(self.handle, count)
assert platforms is not None, "core.BNPluginGetApis returned None"
try:
for i in range(count.value):
result.append(platforms[i].decode("utf-8"))
return result
finally:
core.BNFreePluginPlatforms(platforms, count.value)
@property
def description(self) -> Optional[str]:
"""String short description of the plugin"""
return core.BNPluginGetDescription(self.handle)
@property
def license_text(self) -> Optional[str]:
"""String complete license text for the given plugin"""
return core.BNPluginGetLicenseText(self.handle)
@property
def long_description(self) -> Optional[str]:
"""String long description of the plugin"""
return core.BNPluginGetLongdescription(self.handle)
@deprecation.deprecated(deprecated_in="4.0.5366", details='Use :py:func:`minimum_version_info` instead.')
@property
def minimum_version(self) -> int:
"""Minimum version the plugin was tested on"""
return self.minimum_version_info.build
@property
def minimum_version_info(self) -> 'binaryninja.CoreVersionInfo':
"""Minimum version info the plugin was tested on"""
core_version_info = core.BNPluginGetMinimumVersionInfo(self.handle)
return binaryninja.CoreVersionInfo(core_version_info.major, core_version_info.minor, core_version_info.build)
@property
def maximum_version_info(self) -> 'binaryninja.CoreVersionInfo':
"""Maximum version info the plugin will support"""
core_version_info = core.BNPluginGetMaximumVersionInfo(self.handle)
return binaryninja.CoreVersionInfo(core_version_info.major, core_version_info.minor, core_version_info.build)
@property
def name(self) -> str:
"""String name of the plugin"""
result = core.BNPluginGetName(self.handle)
assert result is not None, "core.BNPluginGetName returned None"
return result
@property
def plugin_types(self) -> List[PluginType]:
"""List of PluginType enumeration objects indicating the plugin type(s)"""
result = []
count = ctypes.c_ulonglong(0)
plugintypes = core.BNPluginGetPluginTypes(self.handle, count)
assert plugintypes is not None, "core.BNPluginGetPluginTypes returned None"
try:
for i in range(count.value):
result.append(PluginType(plugintypes[i]))
return result
finally:
core.BNFreePluginTypes(plugintypes)
@property
def project_url(self) -> Optional[str]:
"""String URL of the plugin's git repository"""
return core.BNPluginGetProjectUrl(self.handle)
@property
def package_url(self) -> Optional[str]:
"""String URL of the plugin's zip file"""
return core.BNPluginGetPackageUrl(self.handle)
@property
def author_url(self) -> Optional[str]:
"""String URL of the plugin author's url"""
return core.BNPluginGetAuthorUrl(self.handle)
@property
def author(self) -> Optional[str]:
"""String of the plugin author"""
return core.BNPluginGetAuthor(self.handle)
@property
def version(self) -> Optional[str]:
"""String version of the plugin"""
return core.BNPluginGetVersion(self.handle)
@property
def install_platforms(self) -> List[str]:
"""List of platforms this plugin can execute on"""
result = []
count = ctypes.c_ulonglong(0)
platforms = core.BNPluginGetPlatforms(self.handle, count)
assert platforms is not None, "core.BNPluginGetPlatforms returned None"
try:
for i in range(count.value):
result.append(platforms[i].decode("utf-8"))
return result
finally:
core.BNFreePluginPlatforms(platforms, count.value)
@property
def being_deleted(self) -> bool:
"""Boolean status indicating that the plugin is being deleted"""
return core.BNPluginIsBeingDeleted(self.handle)
@property
def being_updated(self) -> bool:
"""Boolean status indicating that the plugin is being updated"""
return core.BNPluginIsBeingUpdated(self.handle)
@property
def running(self) -> bool:
"""Boolean status indicating that the plugin is currently running"""
return core.BNPluginIsRunning(self.handle)
@property
def update_pending(self) -> bool:
"""Boolean status indicating that the plugin has updates will be installed after the next restart"""
return core.BNPluginIsUpdatePending(self.handle)
@property
def disable_pending(self) -> bool:
"""Boolean status indicating that the plugin will be disabled after the next restart"""
return core.BNPluginIsDisablePending(self.handle)
@property
def delete_pending(self) -> bool:
"""Boolean status indicating that the plugin will be deleted after the next restart"""
return core.BNPluginIsDeletePending(self.handle)
@property
def update_available(self) -> bool:
"""Boolean status indicating that the plugin has updates available"""
return core.BNPluginIsUpdateAvailable(self.handle)
@property
def dependencies_being_installed(self) -> bool:
"""Boolean status indicating that the plugin's dependencies are currently being installed"""
return core.BNPluginAreDependenciesBeingInstalled(self.handle)
@property
def project_data(self) -> Dict:
"""Gets a json object of the project data field"""
data = core.BNPluginGetProjectData(self.handle)
assert data is not None, "core.BNPluginGetProjectData returned None"
return json.loads(data)
@property
def last_update(self) -> date:
"""Returns a datetime object representing the plugins last update"""
return datetime.fromtimestamp(core.BNPluginGetLastUpdate(self.handle))
class Repository:
"""
``Repository`` is a read-only class. Use RepositoryManager to Enable/Disable/Install/Uninstall plugins.
"""
def __init__(self, handle: core.BNRepositoryHandle) -> None:
self.handle = handle
def __del__(self) -> None:
if core is not None:
core.BNFreeRepository(self.handle)
def __repr__(self) -> str:
return f"<Repository: {self.path}>"
def __getitem__(self, plugin_path: str):
for plugin in self.plugins:
if plugin_path == plugin.path:
return plugin
raise KeyError()
@property
def url(self) -> str:
"""String URL of the git repository where the plugin repository's are stored"""
result = core.BNRepositoryGetUrl(self.handle)
assert result is not None
return result
@property
def path(self) -> str:
"""String local path to store the given plugin repository"""
result = core.BNRepositoryGetRepoPath(self.handle)
assert result is not None
return result
@property
def full_path(self) -> str:
"""String full path the repository"""
result = core.BNRepositoryGetPluginsPath(self.handle)
assert result is not None
return result
@property
def plugins(self) -> List[RepoPlugin]:
"""List of RepoPlugin objects contained within this repository"""
pluginlist = []
count = ctypes.c_ulonglong(0)
result = core.BNRepositoryGetPlugins(self.handle, count)
assert result is not None, "core.BNRepositoryGetPlugins returned None"
try:
for i in range(count.value):
plugin_ref = core.BNNewPluginReference(result[i])
assert plugin_ref is not None, "core.BNNewPluginReference returned None"
pluginlist.append(RepoPlugin(plugin_ref))
return pluginlist
finally:
core.BNFreeRepositoryPluginList(result)
del result
class RepositoryManager:
"""
``RepositoryManager`` Keeps track of all the repositories and keeps the enabled_plugins.json file coherent with
the plugins that are installed/uninstalled enabled/disabled
"""
def __init__(self):
binaryninja._init_plugins()
self.handle = core.BNGetRepositoryManager()
def __getitem__(self, repo_path: str) -> Repository:
for repo in self.repositories:
if repo_path == repo.path:
return repo
raise KeyError()
def check_for_updates(self) -> bool:
"""Check for updates for all managed Repository objects"""
return core.BNRepositoryManagerCheckForUpdates(self.handle)
@property
def repositories(self) -> List[Repository]:
"""List of Repository objects being managed"""
result = []
count = ctypes.c_ulonglong(0)
repos = core.BNRepositoryManagerGetRepositories(self.handle, count)
assert repos is not None, "core.BNRepositoryManagerGetRepositories returned None"
try:
for i in range(count.value):
repo_ref = core.BNNewRepositoryReference(repos[i])
assert repo_ref is not None, "core.BNNewRepositoryReference returned None"
result.append(Repository(repo_ref))
return result
finally:
core.BNFreeRepositoryManagerRepositoriesList(repos)
@property
def plugins(self) -> Dict[str, List[RepoPlugin]]:
"""List of all RepoPlugins in each repository"""
plugin_list = {}
for repo in self.repositories:
plugin_list[repo.path] = repo.plugins
return plugin_list
@property
def default_repository(self) -> Repository:
"""Gets the default Repository"""
repo_handle = core.BNRepositoryManagerGetDefaultRepository(self.handle)
assert repo_handle is not None, "core.BNRepositoryManagerGetDefaultRepository returned None"
repo_handle_ref = core.BNNewRepositoryReference(repo_handle)
assert repo_handle_ref is not None, "core.BNNewRepositoryReference returned None"
return Repository(repo_handle_ref)
def add_repository(self, url: Optional[str] = None, repopath: Optional[str] = None) -> bool:
"""
``add_repository`` adds a new plugin repository for the manager to track.
To remove a repository, restart Binary Ninja (and don't re-add the repository!).
File artifacts will remain on disk under repositories/ file in the User Folder.
Before you can query plugin metadata from a repository, you need to call ``check_for_updates``.
:param str url: URL to the plugins.json containing the records for this repository
:param str repopath: path to where the repository will be stored on disk locally
:return: Boolean value True if the repository was successfully added, False otherwise.
:rtype: Boolean
:Example:
>>> mgr = RepositoryManager()
>>> mgr.add_repository("https://raw.githubusercontent.com/Vector35/community-plugins/master/plugins.json", "community")
True
>>> mgr.check_for_updates()
>>>
"""
if not isinstance(url, str) or not isinstance(repopath, str):
raise ValueError("Expected url or repopath to be of type str.")
return core.BNRepositoryManagerAddRepository(self.handle, url, repopath)