zart

A fast Go-based CIDR and ASN enrichment utility for collecting network intelligence from public routing and geo data sources.

zart combines BGP tables, ASN metadata, Spamhaus CIDR block data, and MaxMind GeoLite2 City data to produce a normalized JSON dataset of network targets enriched with ASN details, country/city information, and dirty CIDR detection.

Overview

This project is designed to answer questions like:

• Which CIDR blocks are associated with a specific ASN?
• Which network ranges are dirty or suspicious?
• Which provider / network role / category does a target belong to?
• What country and city are associated with a given network target?
• How can we quickly filter large network datasets by country, city, ASN category, or CIDR state?

The project reads source data from local templates/ files or downloads them automatically when needed, normalizes the data, and outputs either:

• a JSON file (result.json), or
• a console summary/report, or
• an HTTP API endpoint for filtered results.

Features

• ASN and CIDR enrichment from BGP tables and ASN metadata
• Geo lookup using MaxMind GeoLite2 City database
• ASN metadata fields including category, network role, registered date, and last modified date
• Country and city-based filtering
• CIDR dirty / suspicious range detection using Spamhaus drop data
• Console reporting by network_role, country, city, asn_category, and other keys
• JSON output for downstream automation or analysis
• Simple HTTP API for filtered target queries

Project Structure

.
├── api/
│   └── server.go            # HTTP API server
├── cmd/
│   ├── cmd.go               # CLI flag setup and validation
│   └── logger.go            # logging helpers
├── config/
│   └── config.go            # global config and app metadata
├── handler/
│   ├── downloader.go        # remote source download logic
│   ├── mmdb.go              # GeoIP/MaxMind helpers
│   ├── normalizer.go        # data normalization pipeline
│   ├── output.go            # result/report generation
│   └── ...
├── model/
│   └── model.go             # target and source data models
├── templates/
│   ├── asn-reverse.json     # ASN metadata
│   ├── range-block.json     # Spamhaus route block data
│   ├── table-bgp.json       # BGP targets
│   └── city.mmdb            # MaxMind City DB
├── utils/
│   └── utils.go             # JSON parsing, file helpers, filter logic
├── filter.json              # example filter payload
├── result.json              # generated output example
├── main.go                  # application entrypoint
├── go.mod                   # Go module configuration
├── README.md                # project docs

Data and Sources

The project uses local template datasets stored in the templates/ directory. When required files are missing, the tool can download the needed resources automatically using the --update option.

Installation

Prerequisites

• Go 1.26.1 or newer
• Internet access to download source datasets on first run

Install and build

git clone <repository-url>
cd zart
go mod download
go build .

To run the project directly:

go run . --help

If the required template files are missing, the tool will tell you to use the --update flag to download them.

Usage

Show help

go run . --help

Update local data sources

go run . --update

This downloads the required ASN, BGP, Spamhaus block, and MaxMind City files into templates/.

Query by city and country

go run . --city "Tehran" --country "Iran"

Use a JSON filter file

go run . --filter ./filter.json

Example filter.json:

{
  "country": "Iran",
  "version": "ipv4",
  "cidr_dirty": true
}

Generate a report

go run . --report --base asn_category

Supported report bases include:

• network_role
• country
• asn_category
• city
• cidr_dirty

Start the API server

go run . --api --server 127.0.0.1:8080

The API exposes:

POST /v1/filters

It accepts a JSON object with fields such as country, city, version, asn_category, or cidr_dirty and returns matching targets.

Command Line Flags

Flag	Description
--json	Output in JSON format
--update	Download missing/updated source resources
--api	Run the HTTP API instead of CLI output
--report	Generate a report instead of saving a JSON result
--base	Report base to aggregate on (for example network_role, asn_category)
--city	Filter targets by city
--country	Filter targets by country
--filter	Path to JSON filter file
--server	API bind address such as 127.0.0.1:8080
-v, --version	Print the application version

Output Data Model

Each record in the generated dataset is shaped like this:

{
  "id": 1,
  "cidr": "203.0.113.0/24",
  "cidr_dirty": true,
  "version": "ipv4",
  "asn_code": 64500,
  "asn_description": "Example ASN",
  "location": [42.123, 21.456],
  "asn_category": "business",
  "traffic_hits": 32,
  "network_role": "transit",
  "presented_country_code": "RS",
  "presented_country": "Serbia",
  "presented_city": "Belgrade",
  "asn_country_code": "RS",
  "asn_country": "Serbia",
  "registered_time": "2010-03-01",
  "last_modified": "2026-07-24",
  "prefixes": 12,
  "largest_prefix": 24,
  "tatal_address": "256"
}

Important note: the project currently uses the output field name tatal_address in the model, which is the total ranges that its ASN has in its network.

Example Result

The repository will generate a result.json file that will be generated from a filtered run. It contains normalized entries with fields such as:

{
  "id": 1,
  "cidr": "45.12.34.0/24",
  "asn_code": 215930,
  "asn_description": "CIPHER OPERATIONS DOO BEOGRAD - NOVI BEOGRAD",
  "asn_category": "business",
  "asn_country_code": "RS",
  "asn_country": "Serbia",
  "presented_country": "Serbia",
  "presented_city": "Belgrade"
}

API Example

Request

curl -X POST http://127.0.0.1:8080/v1/filters \
  -H "Content-Type: application/json" \
  -d '{
    "country": "Iran",
    "version": "ipv4",
    "cidr_dirty": true
  }'

Response

[
  {
    "cidr": "185.23.56.0/24",
    "asn_code": 1234,
    "presented_country": "Iran",
    "presented_city": "Tehran",
    "cidr_dirty": true
  }
]

How It Works

The workflow is straightforward:

1. Validate the required data files in templates/.
2. Download missing files if --update is used.
3. Open the GeoLite2 City database.
4. Parse ASN metadata and BGP target tables.
5. Match ASN records to target CIDRs.
6. Enrich each target with network metadata, geo data, and dirty-range status.
7. Save output to result.json or print aggregated reports.

Filtering Behavior

The filter system supports a subset of fields defined in the model and is evaluated by utils.FilterMatches. Supported filter keys include:

• cidr
• cidr_dirty
• version
• asn_code
• asn_description
• asn_category
• traffic_hits
• network_role
• country_code
• country
• city
• registered_time
• last_modified
• prefixes
• largest_prefix

Notes

• The project is intentionally lightweight and data-source-driven.
• It expects template files to exist before processing unless you run --update.
• The code uses a local templates/ directory and writes generated output to the repository root by default.
• The output depends on the downloaded template datasets and their current state at runtime.

Typical Usage Examples

# Download source files
./zart --update

# Query by country and city
./zart --city "Tehran" --country "Iran"

# Generate category report
./zart --report --base asn_category

# Run API
./zart --api --server 127.0.0.1:8080

Summary

zart is a practical network intelligence tool for enriching CIDR and ASN targets with provider metadata, geographic information, and routing context. It is useful for security research, network analysis, and automation tasks where aggregate IP intelligence is needed from structured network datasets.