# Python bindings for F.A.C.C.T. XDR REST API
**Latest Version: 1.0.0**
## Description
The F.A.C.C.T. XDR Python Client enables you to fully integrate F.A.C.C.T. XDR MDP into your malware analysis framework.
F.A.C.C.T. XDR MDP is a Malware Detonation & Research platform designed for deep dynamic analysis and enhanced indicators extraction.
You can use this library with
* [F.A.C.C.T. XDR Cloud](https://xdr.facct.ru) — our Cloud hosted instance
* [On-premise installations of F.A.C.C.T. XDR](https://www.facct.ru/products/managed-xdr/) — for even more power and privacy
## License
The code is written in Python and licensed under MIT.
## Requirements
* python 3.6 or higher
## Getting Started
### Installation
pip install pyxdr
For upgrading `pyxdr` to a more recent version, use
pip install --upgrade pyxdr
### API Key
In order to perform any queries via the API, you will need to get the API token for your F.A.C.C.T. XDR user.
1. Open F.A.C.C.T. XDR web interface.
2. Navigate to "Profile" and click "Generate Auth Token".
3. Copy this token. This is your API Key.
### Sample Code
1. Let's start by sending some file ("sample.exe") for analysis:
```
from pyxdr import MDP
mdp = MDP("MY_API_KEY")
analysis = mdp.upload_file(open("sample.exe", "rb"))
```
2. If you want to detonate some URL, use the next method:
```
analysis = mdp.upload_url("https://very-malicious-url.com")
```
Now we have the `analysis` object.
To update analysis status and get info about it, use the next method:
```
info = analysis.get_info(extended=True)
```
**Notice**: parameter `extended` allows you to get full or short info about analysis process. The short version of the information is as follows:
```
{
"status": "IN PROGRESS" | "FINISHED" | "FAILED",
"verdict": None | True | False,
"report_url": "https://...",
"error": "Some error" # optional field only for "FAILED" status
}
```
If the "verdict" is `True` then object is malicious.
**Notice**: XDR need some time to generate the report url. Until it happens, the response will not contain this field.
3. You can get full report as a dictionary:
```
report = analysis.get_report()
```
4. There is a way to download some detonation artifacts and the report:
```
archived_report = analysis.export_report() # Export report as .tar.
pdf_report = analysis.export_pdf_report() # Export report as PDF
pcap = analysis.export_pcap() # Export all network activity as .pcap file.
screen_video = analysis.export_video() # Export the screen-video of the detonation process.
```
**Notice**: If there is no artifact, all this methods raise `ObjectNotFoundError`.
5. You can check some hash reputation with this method:
```
reputation = mdp.get_hash_reputation("md5", "ac55cf33c4691f863bfb3af8c06a7244")
```
You can get reputation for `md5`, `sha1`, `sha256` hash types.
The method returns a dict object:
```
{
"found": true | false,
"verdict": true | false,
"malware_families": [],
"score": float in [0; 100]
}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/F-A-C-C-T/pyxdr",
"name": "pyxdr",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "security sandbox facct mdp",
"author": "F.A.C.C.T. XDR",
"author_email": "mxdr@facct.ru",
"download_url": "https://files.pythonhosted.org/packages/98/e0/1b429426c5b0f563e709efc3b8d98932ffc063e6e31624377ae2a34a5e3e/pyxdr-1.0.0.tar.gz",
"platform": null,
"description": "# Python bindings for F.A.C.C.T. XDR REST API\n\n**Latest Version: 1.0.0**\n\n## Description\n\nThe F.A.C.C.T. XDR Python Client enables you to fully integrate F.A.C.C.T. XDR MDP into your malware analysis framework.\nF.A.C.C.T. XDR MDP is a Malware Detonation & Research platform designed for deep dynamic analysis and enhanced indicators extraction.\n\nYou can use this library with\n\n * [F.A.C.C.T. XDR Cloud](https://xdr.facct.ru) \u2014 our Cloud hosted instance\n * [On-premise installations of F.A.C.C.T. XDR](https://www.facct.ru/products/managed-xdr/) \u2014 for even more power and privacy\n\n ## License\n\n The code is written in Python and licensed under MIT.\n\n ## Requirements\n\n * python 3.6 or higher\n\n## Getting Started\n\n### Installation\n\n pip install pyxdr\n\nFor upgrading `pyxdr` to a more recent version, use\n \n pip install --upgrade pyxdr\n\n### API Key\n\nIn order to perform any queries via the API, you will need to get the API token for your F.A.C.C.T. XDR user.\n1. Open F.A.C.C.T. XDR web interface.\n2. Navigate to \"Profile\" and click \"Generate Auth Token\".\n3. Copy this token. This is your API Key.\n\n### Sample Code\n\n1. Let's start by sending some file (\"sample.exe\") for analysis:\n```\nfrom pyxdr import MDP\n\nmdp = MDP(\"MY_API_KEY\")\nanalysis = mdp.upload_file(open(\"sample.exe\", \"rb\"))\n```\n2. If you want to detonate some URL, use the next method:\n```\nanalysis = mdp.upload_url(\"https://very-malicious-url.com\")\n```\nNow we have the `analysis` object.\nTo update analysis status and get info about it, use the next method:\n```\ninfo = analysis.get_info(extended=True)\n```\n**Notice**: parameter `extended` allows you to get full or short info about analysis process. The short version of the information is as follows:\n```\n{\n \"status\": \"IN PROGRESS\" | \"FINISHED\" | \"FAILED\",\n \"verdict\": None | True | False,\n \"report_url\": \"https://...\",\n \"error\": \"Some error\" # optional field only for \"FAILED\" status\n}\n```\nIf the \"verdict\" is `True` then object is malicious.\n**Notice**: XDR need some time to generate the report url. Until it happens, the response will not contain this field.\n\n3. You can get full report as a dictionary:\n```\nreport = analysis.get_report()\n```\n4. There is a way to download some detonation artifacts and the report:\n```\narchived_report = analysis.export_report() # Export report as .tar.\npdf_report = analysis.export_pdf_report() # Export report as PDF\npcap = analysis.export_pcap() # Export all network activity as .pcap file.\nscreen_video = analysis.export_video() # Export the screen-video of the detonation process.\n```\n\n**Notice**: If there is no artifact, all this methods raise `ObjectNotFoundError`.\n\n5. You can check some hash reputation with this method:\n```\nreputation = mdp.get_hash_reputation(\"md5\", \"ac55cf33c4691f863bfb3af8c06a7244\")\n```\nYou can get reputation for `md5`, `sha1`, `sha256` hash types.\nThe method returns a dict object:\n```\n{\n \"found\": true | false,\n \"verdict\": true | false,\n \"malware_families\": [],\n \"score\": float in [0; 100]\n}\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "F.A.C.C.T. XDR REST API Python Bindings",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/F-A-C-C-T/pyxdr"
},
"split_keywords": [
"security",
"sandbox",
"facct",
"mdp"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "be774311e7d0df0871d366fd272409107646bf63abb59083f2a644b91928f08a",
"md5": "cec3caf9dc0b34961bdb6d7b95d010c8",
"sha256": "6ead7378aef7dee2c9699721e28fbc374e3be98244071848f7575a809a418305"
},
"downloads": -1,
"filename": "pyxdr-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cec3caf9dc0b34961bdb6d7b95d010c8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 11356,
"upload_time": "2024-08-12T11:53:04",
"upload_time_iso_8601": "2024-08-12T11:53:04.629206Z",
"url": "https://files.pythonhosted.org/packages/be/77/4311e7d0df0871d366fd272409107646bf63abb59083f2a644b91928f08a/pyxdr-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "98e01b429426c5b0f563e709efc3b8d98932ffc063e6e31624377ae2a34a5e3e",
"md5": "68c0b3cbffb7f482e8e8bc7a9277dd47",
"sha256": "b4f230513dc1325ee1a301babcee9288f4bc589c12ab9031b5a95353436604b3"
},
"downloads": -1,
"filename": "pyxdr-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "68c0b3cbffb7f482e8e8bc7a9277dd47",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 11973,
"upload_time": "2024-08-12T11:53:06",
"upload_time_iso_8601": "2024-08-12T11:53:06.216656Z",
"url": "https://files.pythonhosted.org/packages/98/e0/1b429426c5b0f563e709efc3b8d98932ffc063e6e31624377ae2a34a5e3e/pyxdr-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-12 11:53:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "F-A-C-C-T",
"github_project": "pyxdr",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "pyxdr"
}
JSON
