# mercury-python
The goal of the `mercury-python` package is to expose mercury's network protocol analysis functionality via python. The cython interface is given in `mercury.pyx`.
## Installation
### Recommended Installation
```bash
pip install mercury-python
```
### From Source
You will first need to [build mercury](https://wwwin-github.cisco.com/network-intelligence/mercury-transition#building-and-installing-mercury)
and install cython and optionally wheel:
```bash
pip install cython
pip install wheel
```
Within mercury's `src/cython/` directory, `Makefile` will build the package based on the makefile target:
```bash
make # default build in-place
make wheel # generates pip-installable wheel file
```
## Usage
### Initialization
```python
import mercury
libmerc = mercury.Mercury() # initialization for packet parsing
libmerc = mercury.Mercury(do_analysis=True, resources=b'/<path>/<to>/<resources.tgz>') # initialization for analysis
```
### Parsing packets
```python
hex_packet = '5254001235020800273a230d08004500...'
libmerc.get_mercury_json(bytes.fromhex(hex_packet))
```
```javascript
{
"fingerprints": {
"tls": "tls/(0303)(13011303...)((0000)...)"
},
"tls": {
"client": {
"version": "0303",
"random": "0d4e266cf66416689ded443b58d2b12bb2f53e8a3207148e3c8f2be2476cbd24",
"session_id": "67b5db473da1b71fbca9ed288052032ee0d5139dcfd6ea78b4436e509703c0e4",
"cipher_suites": "130113031302c02bc02fcca9cca8c02cc030c00ac009c013c014009c009d002f0035000a",
"compression_methods": "00",
"server_name": "content-signature-2.cdn.mozilla.net",
"application_layer_protocol_negotiation": [
"h2",
"http/1.1"
],
"session_ticket": ""
}
},
"src_ip": "10.0.2.15",
"dst_ip": "13.249.64.25",
"protocol": 6,
"src_port": 32972,
"dst_port": 443,
}
```
### Analysis
There are two methods to invoke mercury's analysis functionality. The first operates on the full hex packet:
```python
libmerc.analyze_packet(bytes.fromhex(hex_packet))
```
```javascript
{
"tls": {
"client": {
"server_name": "content-signature-2.cdn.mozilla.net"
}
},
"fingerprint_info": {
"status": "labeled",
"type": "tls",
"str_repr": "tls/1/(0303)(13011303...)[(0000)...]"
},
"analysis": {
"process": "firefox",
"score": 0.9992411956652674,
"malware": false,
"p_malware": 8.626882751003134e-06
}
```
The second method operates directly on the data features (network protocol fingerprint string and destination context):
```python
libmerc.perform_analysis('tls/1/(0303)(13011303...)[(0000)...]', 'content-signature-2.cdn.mozilla.net', '13.249.64.25', 443)
```
```javascript
{
"fingerprint_info": {
"status": "labeled"
},
"analysis": {
"process": "firefox",
"score": 0.9992158715704546,
"malware": false,
"p_malware": 8.745628825189023e-06
}
}
```
### Static functions
Parsing base64 representations of certificate data:
```python
b64_cert = 'MIIJRDC...'
mercury.parse_cert(b64_cert)
```
output:
```javascript
{
"version": "02",
"serial_number": "00eede6560cd35c0af02000000005971b7",
"signature_identifier": {
"algorithm": "sha256WithRSAEncryption"
},
"issuer": [
{
"country_name": "US"
},
{
"organization_name": "Google Trust Services"
},
{
"common_name": "GTS CA 1O1"
}
],
...
```
Parsing base64 representations of DNS data:
```python
b64_dns = '1e2BgAAB...'
mercury.parse_dns(b64_dns)
```
output:
```javascript
{
"response": {
"question": [
{
"name": "live.github.com.",
"type": "AAAA",
"class": "IN"
}
],
...
```
Raw data
{
"_id": null,
"home_page": "https://github.com/cisco/mercury-python/",
"name": "mercury-python-test",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6.0",
"maintainer_email": null,
"keywords": "tls fingerprinting network traffic analysis",
"author": "Blake Anderson",
"author_email": "blake.anderson@cisco.com",
"download_url": null,
"platform": null,
"description": "# mercury-python\n\nThe goal of the `mercury-python` package is to expose mercury's network protocol analysis functionality via python. The cython interface is given in `mercury.pyx`.\n\n## Installation\n\n### Recommended Installation\n\n```bash\npip install mercury-python\n```\n\n### From Source\n\nYou will first need to [build mercury](https://wwwin-github.cisco.com/network-intelligence/mercury-transition#building-and-installing-mercury)\nand install cython and optionally wheel:\n\n```bash\npip install cython\npip install wheel\n```\n\nWithin mercury's `src/cython/` directory, `Makefile` will build the package based on the makefile target:\n\n```bash\nmake # default build in-place\nmake wheel # generates pip-installable wheel file\n```\n\n## Usage\n\n### Initialization\n\n```python\nimport mercury\n\nlibmerc = mercury.Mercury() # initialization for packet parsing\nlibmerc = mercury.Mercury(do_analysis=True, resources=b'/<path>/<to>/<resources.tgz>') # initialization for analysis\n```\n\n### Parsing packets\n\n```python\nhex_packet = '5254001235020800273a230d08004500...'\nlibmerc.get_mercury_json(bytes.fromhex(hex_packet))\n```\n\n```javascript\n{\n \"fingerprints\": {\n \"tls\": \"tls/(0303)(13011303...)((0000)...)\"\n },\n \"tls\": {\n \"client\": {\n \"version\": \"0303\",\n \"random\": \"0d4e266cf66416689ded443b58d2b12bb2f53e8a3207148e3c8f2be2476cbd24\",\n \"session_id\": \"67b5db473da1b71fbca9ed288052032ee0d5139dcfd6ea78b4436e509703c0e4\",\n \"cipher_suites\": \"130113031302c02bc02fcca9cca8c02cc030c00ac009c013c014009c009d002f0035000a\",\n \"compression_methods\": \"00\",\n \"server_name\": \"content-signature-2.cdn.mozilla.net\",\n \"application_layer_protocol_negotiation\": [\n \"h2\",\n \"http/1.1\"\n ],\n \"session_ticket\": \"\"\n }\n },\n \"src_ip\": \"10.0.2.15\",\n \"dst_ip\": \"13.249.64.25\",\n \"protocol\": 6,\n \"src_port\": 32972,\n \"dst_port\": 443,\n}\n```\n\n\n### Analysis\n\nThere are two methods to invoke mercury's analysis functionality. The first operates on the full hex packet:\n\n```python\nlibmerc.analyze_packet(bytes.fromhex(hex_packet))\n```\n\n```javascript\n{\n \"tls\": {\n \"client\": {\n \"server_name\": \"content-signature-2.cdn.mozilla.net\"\n }\n },\n \"fingerprint_info\": {\n \"status\": \"labeled\",\n \"type\": \"tls\",\n \"str_repr\": \"tls/1/(0303)(13011303...)[(0000)...]\"\n },\n \"analysis\": {\n \"process\": \"firefox\",\n \"score\": 0.9992411956652674,\n \"malware\": false,\n \"p_malware\": 8.626882751003134e-06\n }\n```\n\nThe second method operates directly on the data features (network protocol fingerprint string and destination context):\n\n```python\nlibmerc.perform_analysis('tls/1/(0303)(13011303...)[(0000)...]', 'content-signature-2.cdn.mozilla.net', '13.249.64.25', 443)\n```\n\n```javascript\n{\n \"fingerprint_info\": {\n \"status\": \"labeled\"\n },\n \"analysis\": {\n \"process\": \"firefox\",\n \"score\": 0.9992158715704546,\n \"malware\": false,\n \"p_malware\": 8.745628825189023e-06\n }\n}\n```\n\n\n### Static functions\n\nParsing base64 representations of certificate data:\n\n```python\nb64_cert = 'MIIJRDC...'\nmercury.parse_cert(b64_cert)\n```\noutput:\n```javascript\n{\n \"version\": \"02\",\n \"serial_number\": \"00eede6560cd35c0af02000000005971b7\",\n \"signature_identifier\": {\n \"algorithm\": \"sha256WithRSAEncryption\"\n },\n \"issuer\": [\n {\n \"country_name\": \"US\"\n },\n {\n \"organization_name\": \"Google Trust Services\"\n },\n {\n \"common_name\": \"GTS CA 1O1\"\n }\n ],\n ...\n```\n\nParsing base64 representations of DNS data:\n\n```python\nb64_dns = '1e2BgAAB...'\nmercury.parse_dns(b64_dns)\n```\noutput:\n```javascript\n{\n \"response\": {\n \"question\": [\n {\n \"name\": \"live.github.com.\",\n \"type\": \"AAAA\",\n \"class\": \"IN\"\n }\n ],\n ...\n```\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Python interface into mercury's network protocol fingerprinting and analysis functionality",
"version": "0.1.2",
"project_urls": {
"Homepage": "https://github.com/cisco/mercury-python/"
},
"split_keywords": [
"tls",
"fingerprinting",
"network",
"traffic",
"analysis"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "73062fb55326b26e7595f5d930e19cb134a8d6de80443ae0776fa1b4922e29d0",
"md5": "216117110d7a3ddf43ec98ca7c5a75b5",
"sha256": "a01926463716286f8385c6d63bc07dec46f009e7fdc4a6ea64bde4931e843807"
},
"downloads": -1,
"filename": "mercury_python_test-0.1.2-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"has_sig": false,
"md5_digest": "216117110d7a3ddf43ec98ca7c5a75b5",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.6.0",
"size": 9120514,
"upload_time": "2024-09-09T01:49:50",
"upload_time_iso_8601": "2024-09-09T01:49:50.393529Z",
"url": "https://files.pythonhosted.org/packages/73/06/2fb55326b26e7595f5d930e19cb134a8d6de80443ae0776fa1b4922e29d0/mercury_python_test-0.1.2-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0927e7a5484742b418981da2711759e195859940036a6b46e359c3301dedc630",
"md5": "be1e8200db42f59af7b396f9748faac5",
"sha256": "d12477887fb279a83f67ba271e3b965c7523e0a8e91c1d114fb62b11d52bfc0e"
},
"downloads": -1,
"filename": "mercury_python_test-0.1.2-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"has_sig": false,
"md5_digest": "be1e8200db42f59af7b396f9748faac5",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.6.0",
"size": 9435877,
"upload_time": "2024-09-09T02:37:54",
"upload_time_iso_8601": "2024-09-09T02:37:54.469272Z",
"url": "https://files.pythonhosted.org/packages/09/27/e7a5484742b418981da2711759e195859940036a6b46e359c3301dedc630/mercury_python_test-0.1.2-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-09 01:49:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cisco",
"github_project": "mercury-python",
"github_not_found": true,
"lcname": "mercury-python-test"
}
JSON
