Skip to content

Contributing to NetMap

Thanks for helping. Bug reports, ideas, docs fixes and code are all welcome.

Ways to help

  • Report a bug: open an issue using the Bug report template. Include your OS, Python version and what you clicked. Please don't attach a capture file from your own network unless you are fine with it being public: captures contain your IP addresses and the sites you visited.
  • Suggest a feature: open an issue using the Feature request template.
  • Improve the docs: everything under docs/ is plain Markdown, and the diagrams are Mermaid.
  • Write code: see below.

Development setup

git clone https://github.com/praneeth132006/Network-Tracking-Using-Wireshark-And-Google-Maps.git
cd Network-Tracking-Using-Wireshark-And-Google-Maps
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt -r requirements-dev.txt     # Windows: .venv\Scripts\pip ...
.venv/bin/python -m pytest                                            # run the tests
.venv/bin/python app.py --open                                        # run the dashboard

Where things live

File What it does
analyzer.py The engine: packet decoding, hostnames, GeoIP, alert rules, exporters. Has no web code, so it's the easiest place to start.
app.py Flask + Socket.IO server, live capture and file uploads.
capture_helper.py Small standard-library-only sniffer that runs with admin rights.
main.py Command-line analyzer.
templates/index.html, static/ Dashboard UI (also embedded in the offline HTML report).
tests/ pytest suite. It uses sample-browsing.pcap and never needs root or the internet.

docs/how-it-works.md explains the architecture with diagrams.

Pull request checklist

  1. Branch from main and keep the change focused on one thing.
  2. python -m pytest passes. Add a test for new behaviour, especially new alert rules (see tests/test_analyzer.py).
  3. Match the existing style: plain Python, no new heavy dependencies, and comments only where the why isn't obvious.
  4. Update README.md, docs/ and CHANGELOG.md if users will notice the change.
  5. capture_helper.py must keep using only the Python standard library, because it runs as root outside the virtualenv (see the docstring in that file).

Adding a detection rule

Rules live in TrafficAnalyzer in analyzer.py: _check_flow_rules, _track_syn and _check_domain. Raise an alert with:

self._alert(ts, 'medium', 'my-rule-id', remote_ip, 'Plain-English explanation of what was seen')

Severity is high, medium or low. Alerts are de-duplicated by (rule, ip, message).

Code of conduct

This project follows the Code of Conduct. Be kind.