README
¶
ipdex
Your ultimate IP dex!
ipdex is a simple CLI tool to gather insight about a list of IPs or an IP using the CrowdSec CTI (Cyber Threat Intelligence) API.
Table of Contents
Introduction
ipdex helps analysts and security engineers collect and understand information about IP addresses from CrowdSec CTI.
With this tool you can:
- Check an IP's reputation using CTI
- Scan IP or log files and display detailed reports
- Run CrowdSec Search Queries
- Keep a local history of reports for later inspection
📓 All scanned IPs are cached for 48 hours.
Prerequisites
To use ipdex, you must create a CrowdSec Console account in order to create an API key.
-
Create an account (free or paid):
👉 https://app.crowdsec.net/ -
Go to:
👉Settings > CTI API Keys
and generate a new API key.
You will use this key during the configuration initialisation.
Quickstart
1. Install
Install with Go
If you already have Go installed, you can install ipdex directly from the command line.
⚠️ You need to have Go 1.24+ installed and your
GOPATH/binorGOBINmust be in your system'sPATHenvironment variable to run the binary from anywhere.
go install github.com/crowdsecurity/ipdex/cmd/ipdex@latest
This will download, build, and place the ipdex binary into your $GOBIN directory (usually $HOME/go/bin).
macOS / Linux
Download the binary for your system from the Releases page.
Print your current PATH environment variable to see the folders already in it:
echo $PATH
Move the ipdex binary to one of the folders listed. For example, if /usr/local/bin is in your PATH, you can move the binary like this:
sudo mv ~/Downloads/ipdex_linux_amd64 /usr/local/bin/ipdex
chmod +x /usr/local/bin/ipdex
sudo mv ~/Downloads/ipdex_darwin_arm64 /usr/local/bin/ipdex
chmod +x /usr/local/bin/ipdex
Windows
Download the binary for your system from the Releases page.
If you're using Windows (or WSL), make sure the folder containing the ipdex.exe binary is added to your system PATH.
2. Make sure the binary is in your PATH
To run ipdex from anywhere in your terminal, the binary must be in a folder that's part of your PATH.
3. Initialize the tool
ipdex init
Enter your API key and set your preferences.
4. Query an IP
ipdex 1.2.3.4
5. Scan a file
ipdex file ips.txt
ipdex file /var/log/nginx.log
Configuration
Use the init command to:
- Enter your API key
- Get tips about ipdex
User Guide
All scanned IPs are cached for 48 hours.
Scan an IP
ipdex <IP>
Refresh an IP
ipdex <IP> -r
Scan a file
ipdex <filepath>
Refresh a file
When running ipdex on a file that has been previously scanned, it will update the existing report. Refreshing the file is particularly useful if some IPs are still cached and you wish to refresh the entire report.
ipdex <filepath> -r
Display all reports
ipdex report list
Showing a specific report
ipdex report show <report ID> # -d to see all IPs
Commands
init
Setup your configuration for the first time:
ipdex init
Interactive prompts will help you enter:
- API key (required)
report
Manage your local reports.
List reports
ipdex report list
View a report
ipdex report show 2
Delete a report
ipdex report delete 2
search
You can find the documentation for search queries here.
By default, the since parameter is set to 30d.
- For the free plan, the page size is limited to
10. - For premium plans, the page size increases to
1000.
⚠️ Each queried page counts as 1 quota.
Search IPs reported for a specific CVE
ipdex search "cves:CVE-2025-2748"
Search IPs reported for HTTP scan since 30 minutes
ipdex search 'behaviors.label:"HTTP Scan"' --since 30m
Search malicious VPN or Proxy IPs since 1h and show all IPs
ipdex search 'classifications.classifications.label:"VPN or Proxy" AND reputation:malicious' --since 1h -d
config
Manually view or change your saved config:
ipdex config
Show config
ipdex config show
Set a new API Key
ipdex config set --api-key <API-KEY>
License
MIT License — see the LICENSE file.
Directories