# 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/src/cython/",
"name": "mercury-python",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6.0",
"maintainer_email": "",
"keywords": "tls fingerprinting network traffic analysis",
"author": "Blake Anderson",
"author_email": "blake.anderson@cisco.com",
"download_url": "",
"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": "",
"summary": "Python interface into mercury's network protocol fingerprinting and analysis functionality",
"version": "0.1.2",
"project_urls": {
"Homepage": "https://github.com/cisco/mercury/src/cython/"
},
"split_keywords": [
"tls",
"fingerprinting",
"network",
"traffic",
"analysis"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "750ff1455a6e1443702c048869853598ce9ea486feeb97c9f55e2ef537c162bd",
"md5": "993e9d78448583c5e106ae295d68a4ea",
"sha256": "12853e24ae751d61ec4628dbca6739a5376e05071786437804216fe6b845bfb0"
},
"downloads": -1,
"filename": "mercury_python-0.1.2-cp310-cp310-manylinux_2_28_x86_64.whl",
"has_sig": false,
"md5_digest": "993e9d78448583c5e106ae295d68a4ea",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.6.0",
"size": 9318393,
"upload_time": "2023-05-30T23:10:54",
"upload_time_iso_8601": "2023-05-30T23:10:54.521682Z",
"url": "https://files.pythonhosted.org/packages/75/0f/f1455a6e1443702c048869853598ce9ea486feeb97c9f55e2ef537c162bd/mercury_python-0.1.2-cp310-cp310-manylinux_2_28_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0c2d7c840ce5332f1b7ab0ae891be2016b41399bf393a7df9222acfbfca5994d",
"md5": "3c41b332a5c0080192a8afb064163b33",
"sha256": "e081c56ae4bad6d77710e3247f596eb7cd1afcffa36db311bcd2e20cfd6bdaf9"
},
"downloads": -1,
"filename": "mercury_python-0.1.2-cp311-cp311-manylinux_2_28_x86_64.whl",
"has_sig": false,
"md5_digest": "3c41b332a5c0080192a8afb064163b33",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.6.0",
"size": 9323422,
"upload_time": "2023-05-30T23:11:00",
"upload_time_iso_8601": "2023-05-30T23:11:00.979184Z",
"url": "https://files.pythonhosted.org/packages/0c/2d/7c840ce5332f1b7ab0ae891be2016b41399bf393a7df9222acfbfca5994d/mercury_python-0.1.2-cp311-cp311-manylinux_2_28_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "dc06515bc9a5227773d465e0609220f0da76e59c61e63ab641186e2be3446a7a",
"md5": "1c31957ead6ccc5c12d53417258e6136",
"sha256": "480d58ff8cb1fb7987cd344f65b298ce80b78857d7a6fc03e24c305b6001fc52"
},
"downloads": -1,
"filename": "mercury_python-0.1.2-cp36-cp36m-manylinux_2_28_x86_64.whl",
"has_sig": false,
"md5_digest": "1c31957ead6ccc5c12d53417258e6136",
"packagetype": "bdist_wheel",
"python_version": "cp36",
"requires_python": ">=3.6.0",
"size": 9347235,
"upload_time": "2023-05-30T23:11:05",
"upload_time_iso_8601": "2023-05-30T23:11:05.925979Z",
"url": "https://files.pythonhosted.org/packages/dc/06/515bc9a5227773d465e0609220f0da76e59c61e63ab641186e2be3446a7a/mercury_python-0.1.2-cp36-cp36m-manylinux_2_28_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "987b1bc60de01ce5189ca77092be9d92cfe9b2bac9a2aa9f633b583b30cfc20a",
"md5": "139686e06f1d25bb806c77019af47054",
"sha256": "3049cd64b0625c3ffc4479c337a3e5654c9776641bfab3d7379a0595906485db"
},
"downloads": -1,
"filename": "mercury_python-0.1.2-cp37-cp37m-manylinux_2_28_x86_64.whl",
"has_sig": false,
"md5_digest": "139686e06f1d25bb806c77019af47054",
"packagetype": "bdist_wheel",
"python_version": "cp37",
"requires_python": ">=3.6.0",
"size": 9301690,
"upload_time": "2023-05-30T23:11:09",
"upload_time_iso_8601": "2023-05-30T23:11:09.395299Z",
"url": "https://files.pythonhosted.org/packages/98/7b/1bc60de01ce5189ca77092be9d92cfe9b2bac9a2aa9f633b583b30cfc20a/mercury_python-0.1.2-cp37-cp37m-manylinux_2_28_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "babf97d28e8908692a0c0ceade321d793fbdcfe3f2fa30208645d8d7bd701fe1",
"md5": "9268ce9f174e40981011b77907eb9a12",
"sha256": "7e692526e36c2a2253f549fba3e49ac91663d021e7ce0ec4c26df847527bd0eb"
},
"downloads": -1,
"filename": "mercury_python-0.1.2-cp38-cp38-manylinux_2_28_x86_64.whl",
"has_sig": false,
"md5_digest": "9268ce9f174e40981011b77907eb9a12",
"packagetype": "bdist_wheel",
"python_version": "cp38",
"requires_python": ">=3.6.0",
"size": 9327922,
"upload_time": "2023-05-30T23:11:12",
"upload_time_iso_8601": "2023-05-30T23:11:12.759367Z",
"url": "https://files.pythonhosted.org/packages/ba/bf/97d28e8908692a0c0ceade321d793fbdcfe3f2fa30208645d8d7bd701fe1/mercury_python-0.1.2-cp38-cp38-manylinux_2_28_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f1387b7192dfcb7ce5b275b4e572db8b00727d4adb367a994f27d4ef928eb910",
"md5": "d62992b4ba376edf456697d2fd448d43",
"sha256": "60b980fa312c3d6c114b717dad457eec3e08779c11777d7a651399394d36eee4"
},
"downloads": -1,
"filename": "mercury_python-0.1.2-cp39-cp39-manylinux_2_28_x86_64.whl",
"has_sig": false,
"md5_digest": "d62992b4ba376edf456697d2fd448d43",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.6.0",
"size": 9324249,
"upload_time": "2023-05-30T23:11:18",
"upload_time_iso_8601": "2023-05-30T23:11:18.229464Z",
"url": "https://files.pythonhosted.org/packages/f1/38/7b7192dfcb7ce5b275b4e572db8b00727d4adb367a994f27d4ef928eb910/mercury_python-0.1.2-cp39-cp39-manylinux_2_28_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cd4313c6ca9d0c77e6fa66d488a4b539f4eac44f4f65a36f3d3a258fc0e49d80",
"md5": "ebaac3b4e080ac45b24a2c849ebbe209",
"sha256": "1fef9e08c39b8f71d23b7f02b77ca7874ea652491e2764254f7faa052a5ad33e"
},
"downloads": -1,
"filename": "mercury_python-0.1.2-pp37-pypy37_pp73-manylinux_2_28_x86_64.whl",
"has_sig": false,
"md5_digest": "ebaac3b4e080ac45b24a2c849ebbe209",
"packagetype": "bdist_wheel",
"python_version": "pp37",
"requires_python": ">=3.6.0",
"size": 1947117,
"upload_time": "2023-05-30T23:11:21",
"upload_time_iso_8601": "2023-05-30T23:11:21.595855Z",
"url": "https://files.pythonhosted.org/packages/cd/43/13c6ca9d0c77e6fa66d488a4b539f4eac44f4f65a36f3d3a258fc0e49d80/mercury_python-0.1.2-pp37-pypy37_pp73-manylinux_2_28_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "484d2e0aa52ca9560949cbe9df10b87b3bbd1d6c3956b7e24d2106fa8a629951",
"md5": "bda1c1f3b8052e4c65df2c88a5d51ba0",
"sha256": "e86924edfb25557242666b89bd1f4db76b002ec6ebfe94f1d58105c9da0bec9e"
},
"downloads": -1,
"filename": "mercury_python-0.1.2-pp38-pypy38_pp73-manylinux_2_28_x86_64.whl",
"has_sig": false,
"md5_digest": "bda1c1f3b8052e4c65df2c88a5d51ba0",
"packagetype": "bdist_wheel",
"python_version": "pp38",
"requires_python": ">=3.6.0",
"size": 1940734,
"upload_time": "2023-05-30T23:11:24",
"upload_time_iso_8601": "2023-05-30T23:11:24.345268Z",
"url": "https://files.pythonhosted.org/packages/48/4d/2e0aa52ca9560949cbe9df10b87b3bbd1d6c3956b7e24d2106fa8a629951/mercury_python-0.1.2-pp38-pypy38_pp73-manylinux_2_28_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c6c2abc1fd629c2666583558643ca4d281e1c59dd229f0fcc6758574145bc35b",
"md5": "54cc6f72ad456d4ca66a41b1bbf62e2c",
"sha256": "38df42de66d221062c4cd84a79c966971fe0734977c5b4f4e58ee589eae05b0c"
},
"downloads": -1,
"filename": "mercury_python-0.1.2-pp39-pypy39_pp73-manylinux_2_28_x86_64.whl",
"has_sig": false,
"md5_digest": "54cc6f72ad456d4ca66a41b1bbf62e2c",
"packagetype": "bdist_wheel",
"python_version": "pp39",
"requires_python": ">=3.6.0",
"size": 1940358,
"upload_time": "2023-05-30T23:11:26",
"upload_time_iso_8601": "2023-05-30T23:11:26.960476Z",
"url": "https://files.pythonhosted.org/packages/c6/c2/abc1fd629c2666583558643ca4d281e1c59dd229f0fcc6758574145bc35b/mercury_python-0.1.2-pp39-pypy39_pp73-manylinux_2_28_x86_64.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-30 23:10:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cisco",
"github_project": "mercury",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "mercury-python"
}
JSON
