| Name | vt2m JSON |
| Version |
0.1.16
JSON |
| download |
| home_page | https://github.com/3c7/vt2m |
| Summary | Automatically import results from VirusTotal queries into MISP objects |
| upload_time | 2023-09-06 19:10:19 |
| maintainer | |
| docs_url | None |
| author | 3c7 |
| requires_python | >=3.8,<4.0 |
| license | MIT |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# VirusTotal Query to MISP Objects (vt2m)
While there are multiple Python projects which implement the object creation based on single VirusTotal objects, this
project aims to enable users to directly convert VirusTotal search queries to MISP objects.
**This is work in progress.** Future release will implement handling URLs, Domain and IP objects, too. Right now, only
file objects - as a base for queries - are implemented. These file objects can have related IPs, domains and URLs,
though.
## Installation
```
pip install vt2m
```
## Usage
If you use the script frequently, passing the arguments as environment variables (`MISP_URL`, `MISP_KEY`, `VT_KEY`)
can be useful to save some time. For example, this can be achieved through creating a shell script which passes the
environment variables and executes the command with spaces in front, so it does not show up in the shell history.
Something like this:
```bash
#!/usr/bin/env bash
SAVEIFS=$IFS
IFS=$(echo -en "\n\b")
IFS=$SAVEIFS
MISP_URL="https://my.misp.host.local" MISP_KEY="MyMISPApiKey1234567890" VT_KEY="MyVTApiKey1234567890" /path/to/venv/bin/vt2m "$@"
IFS=$SAVEIFS
```
Changing the IFS is a must, so spaces are not seen as a field seperator.
Overall, `vt2m` supports three commands:
- VirusTotal Intelligence Search via `query`
- Accessing Live Hunting notifications via `notifications` (or `no`)
- Accessing Retrohunt results via `retrohunts` (or `re`)
### VirusTotal Ingelligence Search: `query`
```
Usage: vt2m query [OPTIONS] QUERY
Query VT for files and add them to a MISP event
Arguments:
QUERY VirusTotal Query [required]
Options:
-u, --uuid TEXT MISP event UUID [required]
-U, --url TEXT MISP URL - can be passed via MISP_URL env
-K, --key TEXT MISP API Key - can be passed via MISP_KEY env
-k, --vt-key TEXT VirusTotal API Key - can be passed via VT_KEY
env
-c, --comment TEXT Comment for new MISP objects.
-l, --limit INTEGER Limit of VirusTotal objects to receive
[default: 100]
-L, --limit-relations INTEGER Limit the amount of related objects. Note
that this is for every relation queries.
[default: 40]
-r, --relations TEXT Relations to resolve via VirusTotal,
available relations are: execution_parents,
compressed_parents, bundled_files,
dropped_files, contacted_urls, embedded_urls,
itw_urls, contacted_domains,
embedded_domains, itw_domains, contacted_ips,
embedded_ips, itw_ips, submissions,
communicating_files
-d, --detections INTEGER Amount of detections a related VirusTotal
object must at least have [default: 0]
-D, --extract-domains Extract domains from URL objects and add them
as related object.
-f, --filter TEXT Filtering related objects by matching this
string(s) against json dumps of the objects.
-p, --pivot TEXT Pivot from the given query before resolving
relationships. This must be a valid VT file
relation (execution_parents,
compressed_parents, bundled_files,
dropped_files).
-P, --pivot-limit INTEGER Limit the amount of files returned by a
pivot. [default: 40]
-C, --pivot-comment TEXT Comment to add to the initial pivot object.
--pivot-relationship TEXT MISP relationship type for the relation
between the initial pivot object and the
results. [default: related-to]
--help Show this message and exit.
```
The `query` command supports ingesting files from a VT search, but additional also requesting specific related files or
infrastructure indicators (via `--relations`) and an initial pivot off the files (via `--pivot`). The latter means that,
e.g., you're able to search for files that are commonly dropped or contained within the samples you're actually
searching for and use the "parent" files as your regular result set, enrichting them with additional relationships etc.
Via `--relations` VirusTotal relations can be resolved and added as MISP objects with the specific relations, e.g. the
following graph was created using vt2m:
*Graph created
via `vt2m --uuid <UUID> --limit 5 --relations dropped_files,execution_parents "behaviour_processes:\"ping -n 70\""`*
### VirusTotal Livehunt notifications: `notifications`
```
Usage: vt2m notifications [OPTIONS] COMMAND [ARGS]...
Query and process VT notifications
Options:
--help Show this message and exit.
Commands:
import Import files related to notifications
list List currently available VirusTotal notifications
```
The command allows to list and to import livehunt results via two subcommands.
### VirusTotal Retrohunt results: `retrohunts`
```
Usage: vt2m retrohunts [OPTIONS] COMMAND [ARGS]...
Query for retrohunt results.
Options:
--help Show this message and exit.
Commands:
import Imports results of a retrohunt into a MISP event
list Lists available retrohunts
```
The command allows to list and to import retrohunt results via two subcommands.
## Examples
### Query for hashes
In order to just ingest files you already found via VirusTotal search, you can query for the file hashes in order to
save VirusTotal queries. This way the command only counts towards regular API calls.
`vt2m query --uuid <MISP Event UUID> "<hash 1> <hash 2> <hash 3> ... <hash n>"`
Of course, the same way you're able to include related objects, e.g. contacted URLs, the according domains and dropped
files during execution.
`vt2m query --uuid <MISP Event UUID> --relations contacted_urls,dropped_files --extract-domains "<hash 1> <hash 2> <hash 3> ... <hash n>"`
### Query using VirusTotal Intelligence Searches
Similar as above, you can directly use VirusTotal search queries for ingesting indicators into MISP events:
`vt2m query --uuid <MISP Event UUID> --relations contacted_urls,dropped_files --extract-domains "imphash:<imphash>"`
### Pivot before query
Sometimes it's necessary to pivot before receiving the actual files. This is useful, if files drop a common file during
execution, or archives have a common file bundled. This can be done this way:
`vt2m query --uuid <MISP Event UUID> --relations contacted_domains,bundled_files --detections 3 --pivot compressed_parents --pivot-comment "RC4 Key" --pivot-limit 20 --pivot-relationship contained-within 99c9440a84cdc428ce140de901452eb334faec49f1f6258acdde1ddcbb34376e`
As this command introduces some parameters that might be not self-explanatory, here is a small breakdown of them:
| Parameter | Description |
|----------------------------------------|-------------------------------------------------------------------------------------|
| `--uuid` | The UUID of the MISP event which will be the ingestion target |
| `--relations` | VirusTotal relations to query for |
| `--detections 3` | Filter for related objects with at least 3 AV detections |
| `--pivot compressed_parents` | Enable pivot mode and pivot via the relation given |
| `--pivot-comment` | Comment to add to the MISP object pivoted from |
| `--pivot-limit 20` | Limit the pivot to 20 objects |
| `--pivot-relationship contaned-within` | MISP relationship between the pivoted object and the results, default is related-to |
The above query is resulting in the following MISP graph:
Raw data
{
"_id": null,
"home_page": "https://github.com/3c7/vt2m",
"name": "vt2m",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "",
"author": "3c7",
"author_email": "3c7@posteo.de",
"download_url": "https://files.pythonhosted.org/packages/04/74/4b70ab5509e2578f077b33a6800cbad3cf751e476836194a539c9803c589/vt2m-0.1.16.tar.gz",
"platform": null,
"description": "# VirusTotal Query to MISP Objects (vt2m)\n\nWhile there are multiple Python projects which implement the object creation based on single VirusTotal objects, this\nproject aims to enable users to directly convert VirusTotal search queries to MISP objects.\n**This is work in progress.** Future release will implement handling URLs, Domain and IP objects, too. Right now, only\nfile objects - as a base for queries - are implemented. These file objects can have related IPs, domains and URLs,\nthough.\n\n## Installation\n\n```\npip install vt2m\n```\n\n## Usage\n\nIf you use the script frequently, passing the arguments as environment variables (`MISP_URL`, `MISP_KEY`, `VT_KEY`)\ncan be useful to save some time. For example, this can be achieved through creating a shell script which passes the\nenvironment variables and executes the command with spaces in front, so it does not show up in the shell history.\nSomething like this:\n\n```bash\n#!/usr/bin/env bash\n\nSAVEIFS=$IFS\nIFS=$(echo -en \"\\n\\b\")\nIFS=$SAVEIFS\n MISP_URL=\"https://my.misp.host.local\" MISP_KEY=\"MyMISPApiKey1234567890\" VT_KEY=\"MyVTApiKey1234567890\" /path/to/venv/bin/vt2m \"$@\"\nIFS=$SAVEIFS\n```\n\nChanging the IFS is a must, so spaces are not seen as a field seperator.\n\nOverall, `vt2m` supports three commands:\n\n- VirusTotal Intelligence Search via `query`\n- Accessing Live Hunting notifications via `notifications` (or `no`)\n- Accessing Retrohunt results via `retrohunts` (or `re`)\n\n### VirusTotal Ingelligence Search: `query`\n\n```\nUsage: vt2m query [OPTIONS] QUERY\n\n Query VT for files and add them to a MISP event\n\nArguments:\n QUERY VirusTotal Query [required]\n\nOptions:\n -u, --uuid TEXT MISP event UUID [required]\n -U, --url TEXT MISP URL - can be passed via MISP_URL env\n -K, --key TEXT MISP API Key - can be passed via MISP_KEY env\n -k, --vt-key TEXT VirusTotal API Key - can be passed via VT_KEY\n env\n -c, --comment TEXT Comment for new MISP objects.\n -l, --limit INTEGER Limit of VirusTotal objects to receive\n [default: 100]\n -L, --limit-relations INTEGER Limit the amount of related objects. Note\n that this is for every relation queries.\n [default: 40]\n -r, --relations TEXT Relations to resolve via VirusTotal,\n available relations are: execution_parents,\n compressed_parents, bundled_files,\n dropped_files, contacted_urls, embedded_urls,\n itw_urls, contacted_domains,\n embedded_domains, itw_domains, contacted_ips,\n embedded_ips, itw_ips, submissions,\n communicating_files\n -d, --detections INTEGER Amount of detections a related VirusTotal\n object must at least have [default: 0]\n -D, --extract-domains Extract domains from URL objects and add them\n as related object.\n -f, --filter TEXT Filtering related objects by matching this\n string(s) against json dumps of the objects.\n -p, --pivot TEXT Pivot from the given query before resolving\n relationships. This must be a valid VT file\n relation (execution_parents,\n compressed_parents, bundled_files,\n dropped_files).\n -P, --pivot-limit INTEGER Limit the amount of files returned by a\n pivot. [default: 40]\n -C, --pivot-comment TEXT Comment to add to the initial pivot object.\n --pivot-relationship TEXT MISP relationship type for the relation\n between the initial pivot object and the\n results. [default: related-to]\n --help Show this message and exit.\n```\n\nThe `query` command supports ingesting files from a VT search, but additional also requesting specific related files or\ninfrastructure indicators (via `--relations`) and an initial pivot off the files (via `--pivot`). The latter means that,\ne.g., you're able to search for files that are commonly dropped or contained within the samples you're actually\nsearching for and use the \"parent\" files as your regular result set, enrichting them with additional relationships etc.\n\nVia `--relations` VirusTotal relations can be resolved and added as MISP objects with the specific relations, e.g. the\nfollowing graph was created using vt2m:\n\n*Graph created\nvia `vt2m --uuid <UUID> --limit 5 --relations dropped_files,execution_parents \"behaviour_processes:\\\"ping -n 70\\\"\"`*\n\n### VirusTotal Livehunt notifications: `notifications`\n\n```\nUsage: vt2m notifications [OPTIONS] COMMAND [ARGS]...\n\n Query and process VT notifications\n\nOptions:\n --help Show this message and exit.\n\nCommands:\n import Import files related to notifications\n list List currently available VirusTotal notifications\n```\n\nThe command allows to list and to import livehunt results via two subcommands.\n\n### VirusTotal Retrohunt results: `retrohunts`\n\n```\nUsage: vt2m retrohunts [OPTIONS] COMMAND [ARGS]...\n\n Query for retrohunt results.\n\nOptions:\n --help Show this message and exit.\n\nCommands:\n import Imports results of a retrohunt into a MISP event\n list Lists available retrohunts\n```\n\nThe command allows to list and to import retrohunt results via two subcommands.\n\n## Examples\n\n### Query for hashes\n\nIn order to just ingest files you already found via VirusTotal search, you can query for the file hashes in order to\nsave VirusTotal queries. This way the command only counts towards regular API calls.\n\n`vt2m query --uuid <MISP Event UUID> \"<hash 1> <hash 2> <hash 3> ... <hash n>\"`\n\nOf course, the same way you're able to include related objects, e.g. contacted URLs, the according domains and dropped\nfiles during execution.\n\n`vt2m query --uuid <MISP Event UUID> --relations contacted_urls,dropped_files --extract-domains \"<hash 1> <hash 2> <hash 3> ... <hash n>\"`\n\n### Query using VirusTotal Intelligence Searches\n\nSimilar as above, you can directly use VirusTotal search queries for ingesting indicators into MISP events:\n\n`vt2m query --uuid <MISP Event UUID> --relations contacted_urls,dropped_files --extract-domains \"imphash:<imphash>\"`\n\n### Pivot before query\n\nSometimes it's necessary to pivot before receiving the actual files. This is useful, if files drop a common file during\nexecution, or archives have a common file bundled. This can be done this way:\n\n`vt2m query --uuid <MISP Event UUID> --relations contacted_domains,bundled_files --detections 3 --pivot compressed_parents --pivot-comment \"RC4 Key\" --pivot-limit 20 --pivot-relationship contained-within 99c9440a84cdc428ce140de901452eb334faec49f1f6258acdde1ddcbb34376e`\n\nAs this command introduces some parameters that might be not self-explanatory, here is a small breakdown of them:\n\n| Parameter | Description |\n|----------------------------------------|-------------------------------------------------------------------------------------|\n| `--uuid` | The UUID of the MISP event which will be the ingestion target |\n| `--relations` | VirusTotal relations to query for |\n| `--detections 3` | Filter for related objects with at least 3 AV detections |\n| `--pivot compressed_parents` | Enable pivot mode and pivot via the relation given |\n| `--pivot-comment` | Comment to add to the MISP object pivoted from |\n| `--pivot-limit 20` | Limit the pivot to 20 objects |\n| `--pivot-relationship contaned-within` | MISP relationship between the pivoted object and the results, default is related-to |\n\nThe above query is resulting in the following MISP graph:\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Automatically import results from VirusTotal queries into MISP objects",
"version": "0.1.16",
"project_urls": {
"Homepage": "https://github.com/3c7/vt2m",
"Repository": "https://github.com/3c7/vt2m"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "824447d43cc2b84d6569d8afa2f969c15ecb6f1871ff0cfe5297c0780c34a95b",
"md5": "b85ceced6d4cd26698ac1d0c71c1fe6a",
"sha256": "5c8427200bccc164b220ac401d0ec690782909d48252e44fc14f8dceb220287e"
},
"downloads": -1,
"filename": "vt2m-0.1.16-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b85ceced6d4cd26698ac1d0c71c1fe6a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 261239,
"upload_time": "2023-09-06T19:10:17",
"upload_time_iso_8601": "2023-09-06T19:10:17.083007Z",
"url": "https://files.pythonhosted.org/packages/82/44/47d43cc2b84d6569d8afa2f969c15ecb6f1871ff0cfe5297c0780c34a95b/vt2m-0.1.16-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "04744b70ab5509e2578f077b33a6800cbad3cf751e476836194a539c9803c589",
"md5": "59b42418456ed466c9b452308a93bc7c",
"sha256": "51056f651e95ffe0ed46679e9e2322a56da155626ebb023ad828492e62f7e9e9"
},
"downloads": -1,
"filename": "vt2m-0.1.16.tar.gz",
"has_sig": false,
"md5_digest": "59b42418456ed466c9b452308a93bc7c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 260228,
"upload_time": "2023-09-06T19:10:19",
"upload_time_iso_8601": "2023-09-06T19:10:19.526841Z",
"url": "https://files.pythonhosted.org/packages/04/74/4b70ab5509e2578f077b33a6800cbad3cf751e476836194a539c9803c589/vt2m-0.1.16.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-06 19:10:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "3c7",
"github_project": "vt2m",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "vt2m"
}
