Introducing the CrowdSec IPDEX: Your Ultimate IP Index

The CrowdSec team has some exciting news to share! 

We are thrilled to introduce the latest addition to the CrowdSec toolkit, the CrowdSec IPDEX.

IPDEX is a simple CLI tool that uses the CrowdSec CTI API to gather insight about a single IP or a list of IPs.

Let’s jump in and explore this new and handy IP index.

TL;DR

IPDEX is a simple tool, fast and easy to set up. With IPDEX you can: 

• Check an IP’s reputation using CTI 
• Scan log or IP 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.

Keep reading for a quick tutorial on how to perform certain tasks with IPDEX!

The story behind IPDEX

The CrowdSec team created IPDEX to add an additional tool to our users’ toolkit. It helps analysts and security engineers collect and understand information about IP addresses from CrowdSec CTI. 

IPDEX is a simple and easy-to-use tool with a few functionalities. Its main feature is the ability to query any IP address at any time to see its basic and threat information. 

Since it is common to have a file of IPs (extracted from your firewall, for example) or a log file from your web server or any other exposed services, IPDEX is also capable of reading those files, extracting the IPs, enriching them against CrowdSec CTI, and generating a report.

The generated reports are saved and can be consulted later. Last but not least, the tool can also query the CrowdSec CTI with the CrowdSec Search Queries.

IPDEX vs. CTI API

While the CrowdSec CTI API is free (with a maximum of 30 requests daily), documented, and can be easily requested with a command-line tool such as curl or wget, it returns JSON data that can be hard to read for humans. 

With IPDEX, within seconds, it is possible to see if an IP is malicious or not, if it has been seen recently, for what type of behaviors or CVEs it is known for, etc. With CrowdSec CTI API directly, it is also not possible to scan a log file to get information about the IP addresses in the file. Using IPDEX, you can easily get reports about IP addresses found in any files, including log files.

Getting started with IPDEX

Before installing IPDEX, you need to grab an API key from the CrowdSec Console. If you don’t have an account, create one, and visit the CTI API keys setting page to create your API key.

There are two ways to install IPDEX.

1. If you have Go installed, you can just run the following command to install IPDEX:
   go install github.com/crowdsecurity/ipdex/cmd/ipdex@v0.0.1
   Note: You need to have Go 1.24+ installed and your GOPATH/bin or GOBIN must be in your system’s PATH environment variable to run the binary from anywhere.
2. Download the IPDEX binary from the Releases page and move it to /usr/local/bin or any other folder that is part of your $PATH environment variable.

Once you have your API key and IPDEX installed, you still need to initialize it. To do so, run ipdex init and enter your CrowdSec API key when you are asked for it.

Congrats! You can now use IPDEX in your daily tasks.

Let’s take a look at the IPDEX user guide to learn how to use it.

IPDEX user guide

In the super simple tutorial below, I’ll show you how to perform certain tasks with IPDEX.

To query an IP address from the CrowdSec CTI, run ipdex <IP_ADDRESS>.

To run IPDEX against a file of IPs, use the command ipdex <file_path>.

Note: This can be a CSV file, a JSON file, or a file containing one IP per line.

To run IPDEX against a log file, use this command: ipdex <logfile_path>.

To show you how to run a CrowdSec Search Query with IPDEX, I’ll use CVE-2024-57727 as an example. With the command below, I’ll search for IPs exploiting CVE-2024-57727 and request information for the past 4 hours.

ipdex search 'cves:CVE-2024-57727' --since 4h

To list all reports generated from scanned files or search queries, use the command ipdex report list.

To request IPDEX to show you an existing report with IP information, use the command ipdex report show <report_id>.

To show the IPDEX configuration currently used, use the command ipdex config show.

And lastly, to update the IPDEX configuration and replace the API key, use the command ipdex config set –api-key <API_KEY>.

All set to IPDEX it!

We are eager for all of you to try this new handy tool and let us know what you think! Don’t forget to reach out to us on Discord or Discourse with questions and feedback.