==========
PlotCap
==========
PlotCap - a simple network visualization tool.
.. image:: preview.png
:align: center
:alt: Sample
.. contents:: Table of Contents
Introduction
============
PlotCap is a simple command line tool written in Python and based on PyVis, that parses network capture files (produced by tools such as tcpdump or Wireshark) to render a graph of the network topology in a web page.
PlotCap was designed for red team engagements, with the aim of quickly mapping out relationships between devices ("nodes") in a network.
Target groups are: network administrators, penetration testers and curious people.
Visualization can be performed at layer 2 (MAC addresses) and layer 3 (IP addresses).
Layer 2 is the default. The tool attempts to resolve MAC addresses unless directed otherwise.
Install
=======
You can install plotcap on your system by using pipx:
.. code-block:: bash
pipx install git+https://github.com/darknetehf/plotcap.git
And optionally:
.. code-block:: bash
pipx ensurepath
This will add '~/.local/bin' to your PATH environment variable.
Usage
=====
.. code-block:: bash
plotcap -f capture.cap
This is equivalent to:
.. code-block:: bash
plotcap -f capture.cap --layer2
or:
.. code-block:: bash
plotcap -f capture.cap --layer2 --resolve-oui
Do not resolve MAC addresses:
.. code-block:: bash
plotcap -f capture.cap --layer2 --no-resolve-oui
Show IP addresses:
.. code-block:: bash
plotcap -f capture.cap --layer3
To increase **verbosity** add ``-v`` or ``-vv`` for debugging.
API
===
A convenience API is available if you just want to parse the .pcap file and reuse the results, but don't want a graphical representation.
.. code-block:: python
from plotcap.api import parse_file
pcap_file = "/tmp/test.pcap"
conversations = parse_file(pcap_file=pcap_file, layer=2)
for conversation, packet_count in conversations.items():
print(f"src: {conversation.src} - dst: {conversation.dst} - packets: {packet_count}")
Limitations
===========
- Although this is a command line tool, it requires a graphical environment and a web browser to render network maps. On headless systems we suggest using Xvfb to set up virtual sessions.
- PlotCap was tested on Linux only
- MAC addresses may not always be resolved to manufacturer names, especially if address randomization comes into play
- See the TODO file for more missing features
Raw data
{
"_id": null,
"home_page": "https://github.com/darknetehf/plotcap",
"name": "plotcap",
"maintainer": "Darknet ehf",
"docs_url": null,
"requires_python": "<4.0,>=3.11",
"maintainer_email": "info@labs.darknet.com",
"keywords": "packaging, poetry",
"author": "Darknet ehf",
"author_email": "info@labs.darknet.com",
"download_url": "https://files.pythonhosted.org/packages/81/21/4156422387e6c10ae0f1e2ac4e0460a921a07f0f4217f6d1143ce81e704f/plotcap-1.1.1.tar.gz",
"platform": null,
"description": "==========\nPlotCap\n==========\n\nPlotCap - a simple network visualization tool.\n\n.. image:: preview.png\n :align: center\n :alt: Sample\n\n.. contents:: Table of Contents\n\nIntroduction\n============\n\nPlotCap is a simple command line tool written in Python and based on PyVis, that parses network capture files (produced by tools such as tcpdump or Wireshark) to render a graph of the network topology in a web page.\n\nPlotCap was designed for red team engagements, with the aim of quickly mapping out relationships between devices (\"nodes\") in a network.\nTarget groups are: network administrators, penetration testers and curious people.\n\nVisualization can be performed at layer 2 (MAC addresses) and layer 3 (IP addresses).\nLayer 2 is the default. The tool attempts to resolve MAC addresses unless directed otherwise.\n\nInstall\n=======\n\nYou can install plotcap on your system by using pipx:\n\n.. code-block:: bash\n\n pipx install git+https://github.com/darknetehf/plotcap.git\n\nAnd optionally:\n\n.. code-block:: bash\n\n pipx ensurepath\n\nThis will add '~/.local/bin' to your PATH environment variable.\n\nUsage\n=====\n\n.. code-block:: bash\n\n plotcap -f capture.cap\n\nThis is equivalent to:\n\n.. code-block:: bash\n\n plotcap -f capture.cap --layer2\n\nor:\n\n.. code-block:: bash\n\n plotcap -f capture.cap --layer2 --resolve-oui\n\nDo not resolve MAC addresses:\n\n.. code-block:: bash\n\n plotcap -f capture.cap --layer2 --no-resolve-oui\n\nShow IP addresses:\n\n.. code-block:: bash\n\n plotcap -f capture.cap --layer3\n\nTo increase **verbosity** add ``-v`` or ``-vv`` for debugging.\n\nAPI\n===\n\nA convenience API is available if you just want to parse the .pcap file and reuse the results, but don't want a graphical representation.\n\n.. code-block:: python\n\n from plotcap.api import parse_file\n\n pcap_file = \"/tmp/test.pcap\"\n conversations = parse_file(pcap_file=pcap_file, layer=2)\n for conversation, packet_count in conversations.items():\n print(f\"src: {conversation.src} - dst: {conversation.dst} - packets: {packet_count}\")\n\nLimitations\n===========\n\n- Although this is a command line tool, it requires a graphical environment and a web browser to render network maps. On headless systems we suggest using Xvfb to set up virtual sessions.\n- PlotCap was tested on Linux only\n- MAC addresses may not always be resolved to manufacturer names, especially if address randomization comes into play\n- See the TODO file for more missing features\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "PlotCap - a simple network visualization tool",
"version": "1.1.1",
"project_urls": {
"Homepage": "https://github.com/darknetehf/plotcap",
"Repository": "https://github.com/darknetehf/plotcap"
},
"split_keywords": [
"packaging",
" poetry"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bc3a9ab11dc72bfcfa188eb1d047387737613df1b42fbc22b721e4a726158ae7",
"md5": "1b1b47ec41e96e203033c7308f82aefc",
"sha256": "f96634f31da6d5afb08a76a630a3a9a997f9cbb94b064364cace465560ada85d"
},
"downloads": -1,
"filename": "plotcap-1.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1b1b47ec41e96e203033c7308f82aefc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 7618,
"upload_time": "2024-08-01T23:04:04",
"upload_time_iso_8601": "2024-08-01T23:04:04.810316Z",
"url": "https://files.pythonhosted.org/packages/bc/3a/9ab11dc72bfcfa188eb1d047387737613df1b42fbc22b721e4a726158ae7/plotcap-1.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "81214156422387e6c10ae0f1e2ac4e0460a921a07f0f4217f6d1143ce81e704f",
"md5": "b9b97e060d38c9bf7b22c659cf928831",
"sha256": "6f7263c8933ca465402be8d2886cd81391fa6a1ea802a7c76fd9852d53502337"
},
"downloads": -1,
"filename": "plotcap-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "b9b97e060d38c9bf7b22c659cf928831",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 5846,
"upload_time": "2024-08-01T23:04:06",
"upload_time_iso_8601": "2024-08-01T23:04:06.185736Z",
"url": "https://files.pythonhosted.org/packages/81/21/4156422387e6c10ae0f1e2ac4e0460a921a07f0f4217f6d1143ce81e704f/plotcap-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-01 23:04:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "darknetehf",
"github_project": "plotcap",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "plotcap"
}
JSON
