Horus, a Python command hub for OSINT and forensic work

Horus packs many recon commands behind one horus.py entry point

Horus is a Python script that acts as a command dispatcher rather than a library. The repository root holds horus.py next to a src/ directory, and the project's own description calls it an all-in-one tool for investigation assistance, from API work to compiling data. The command names referenced in the documentation give the shape of the tool: there is an 'apicon' command for API setup, a 'pvpn' command for ProtonVPN, an 'ovpn' command for OpenVPN, and a 'geolock' command that handles location-related work. The intended-features graphic in the repository marks each capability with a colour, green for fully implemented, yellow for partial, and red for planned, so the scope is presented as a work in progress rather than a finished product set.

What makes the project useful to a practitioner is the shape of the entry point. Instead of writing a separate script for each lookup, an investigator types one program name and picks a subcommand. For a working directory, that means one checkout, one dependency install, and one file to launch. The trade-off is that the tool sits on top of a lot of other people's work: the module names and the acknowledgements section credit code from the Loki encryption toolset by Fox and Askerdyne Ltd. Horus is best read as an assembly layer that puts several utilities behind one consistent prompt, not as a novel implementation of forensics.

api_config.json keeps paid credentials in a file you must clean before pushing

API configuration is the friction point of the whole project, and the documentation is unusually blunt about it. Keys are entered manually in a JSON file at /src/modules/var/pipes/api_config.json, or set through the 'apicon' command. The file ships inside the source tree, which means every default clone contains the slot where your own Shodan key would go, and the warning in the documentation says that anyone contributing or testing through a public fork must remove their API keys from the JSON file before pushing changes. That is a workflow hazard rather than a hypothetical one, because the natural instinct when fixing a bug is to edit and open a pull request.

Several commands depend on third-party services, so a key is not optional for most of the interesting paths. The documentation is specific about Shodan: it is a paid API, a subscription is required for the API to work, and the location-related functionality that Horus offers under 'geolock' covers only part of what Shodan can do. The broader feature list covers location, crypto and decryption, steganography, and encryption work, so more than one of these commands is likely to expect a service account that you pay for. The path in the file itself is a hint about the architecture: keys live under a var and pipes tree inside src/modules, which suggests a deliberate separation between module code and runtime values.

The install is a clone, a requirements file, and one word that changes on Windows

Installation is short because the project assumes a Python environment you already control. The documented sequence is to clone the repository, move into the horus directory (not the outermost folder), install the dependencies, and launch the entry point. The dependency list is pinned in requirements.txt, and the launcher differs only in the interpreter name between platforms.

pip install -r requirements.txt

After that, the same script runs under a different command on Windows:

python3 horus.py

py horus.py

The first block is the Linux and macOS invocation, the second is the Windows one. There is no packaging step, no container image, and no entry in the project's build configuration that installs a console script. The pyproject.toml file names the project horus, but its version field is set to 0.0.0 and it lists dependencies as a separate set of names, which means the file describes a buildable project on paper rather than a distribution that the documentation tells you to install. For a reviewer that is a mild annoyance: the pinned requirements.txt is the file that actually determines what you get.

Two commands also need binaries that pip cannot supply. The documentation notes that protonvpn-cli is required for the 'pvpn' command and that the OpenVPN CLI is required for the 'ovpn' command, so those two subcommands fail on a machine where those programs are absent.

The dependency list mixes Python packages with programs that are not Python

requirements.txt pins a broad spread of packages, and it is worth reading the list rather than the marketing line. Alongside shodan 1.31.0, cryptography 48.0.1, colorama 0.4.6 and Requests 2.33.0, it includes exif 1.6.0, pytube 15.0.0, pyshark 0.6, python-nmap 0.7.1, whois 1.20240129.2 and dnspython 2.6.1. The presence of exif and pyshark points to image metadata and packet capture work, while dnspython and whois indicate name and domain lookups. pytest 9.0.3 is also in the same file, so the test dependency is mixed into the runtime list rather than kept in a separate development file.

The pyproject.toml list tells a different story, with shodan, dhooks, nmap, colorama, cryptography, hashcat, protonvpn-cli and onionshare_cli. Two entries there are notable: dhooks and hashcat. Combined with the README note about external CLI programs, the picture is that a number of Horus subcommands are wrappers that call other tools and parse their output. That design keeps the code small but pushes the real work, and the reliability, onto the wrapped programs.

The two files also disagree with each other on versions and on membership. Requirements is pinned exactly and includes pytest, exif, pytube, pyshark, whois and dnspython. The pyproject list is unpinned and includes dhooks, hashcat and nmap as bare names. If you install from requirements.txt you do not get the pyproject dependency set, and the reverse is also true.

The geolock command answers with a general lookups API, not the paid one

Geolocation is the part of Horus with the clearest boundary between what the free path gives you and what the subscription path gives you. The documentation states that a lot of Shodan's location-related functionality is available in 'geolock', but that more detailed features require the Shodan API. That is a candid framing, and it means a new user can evaluate the location command without paying anything, then decide whether the paid subscription is worth it for the deeper lookups.

The interesting design question here is what 'geolock' does with a coarse answer. A location that comes from free lookups is typically city or country level, and the command name suggests the tool is trying to pin something down more tightly than a raw IP lookup would. The documentation does not say which sources it queries or how it reconciles conflicting results, and it does not give an example of the output format. If you plan to use the result in a report, that gap matters: without a documented output shape, you cannot script around it or assert on it in a test.

This is where the tool's character becomes clear. Horus exposes a large surface with a small amount of documentation per command. The colour-coded feature table signals which commands are done, but the prose concentrates on the two things a newcomer needs first, which are how to install and where to put the keys.

A single maintainer and a two-year gap between the last tag and the last push

The maintenance picture is uneven. The most recent release tag is v1.2.7, published on 2024-07-10, preceded by v1.2.6 on 2024-06-30 and v1.2.5 on 2024-06-29, so three versions landed within about two weeks in mid 2024. The last push to the repository was on 2026-07-29, which means the default branch has moved since those tags were cut, but the release history itself has not been updated in a little over two years. The project is not archived, and the default branch is main.

The project lead and sole listed maintainer is 6abd, who is described as both project lead and developer. Four other people appear in the acknowledgements as previous roles: a former project manager, a former QA engineer, a former senior developer and a former junior developer. The contributing section says bugs and feature requests should go through issues with the appropriate tag, that pull requests will be reviewed, and that long-term maintainers should make contact directly. That is a project structured around one decision maker.

Licensing is GPL-3.0, so redistribution of modified versions carries the copyleft obligations of that licence, including the requirement to keep the licence text and to publish source for derivatives. That is a licensing fact rather than legal advice, but it is worth checking against your organisation's policy before you vendor the code into a toolchain. The same applies to the third-party code credited in the acknowledgements, since the Loki encryption material is attributed rather than rewritten.

Editorial conclusion

Horus fits an investigator who wants one command entry point for geolocation, decryption and steganography checks and is willing to supply the paid API keys and outside binaries it shells out to. It does not fit a team that needs documented output formats, a testable command surface, or a maintained dependency set, because the last push was on 2026-07-29 and only one person is listed as maintainer. Before adopting it, open src/modules/var/pipes/api_config.json, read the requirements list, and run the command you actually need on a single target to see whether its output is fit for evidence.

Frequently asked questions

Official sources

1. 6abd/horus on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases