Dibbler

Dibbler is a standalone Windows PowerShell analyst tool for enriching CSV files with IP geolocation and network ownership data using DuckDB and DuckDB's MaxMind community extension.

It is named after the dibbler (Parantechinus apicalis), an endangered marsupial native to south west Western Australia.

Current Scope

• CSV input and CSV output.
• Single CSV files, multiple explicit CSV files, or a non-recursive folder of CSV files.
• Analyst-selected IP columns.
• DuckDB-managed enrichment using GeoLite Country, City, and ASN databases.
• One enriched CSV output per source CSV.
• Source evidence files are not modified.

Requirements

• Windows.
• Windows PowerShell 5.1 or PowerShell 7.
• Network access for first-time downloads unless DuckDB and GeoLite databases are already present.

Dibbler can download:

• DuckDB CLI from https://github.com/duckdb/duckdb/releases/latest
• GeoLite .mmdb files from https://github.com/P3TERX/GeoLite.mmdb/releases/latest

Quick Start

Open PowerShell in the Dibbler folder:

.\Run-Dibbler.ps1

Use the GUI tabs in order:

1. Setup: check or download DuckDB and GeoLite files.
2. Source: add CSV files or a folder, then inspect headers.
3. Mapping: confirm one or more IP columns.
4. Run: choose output folder and run enrichment.
5. Logs: review runtime log output.

Headless Setup

Download missing dependencies:

.\Run-Dibbler.ps1 -NoGui -InstallDuckDb -InstallGeoLite

Force re-download:

.\Run-Dibbler.ps1 -NoGui -InstallDuckDb -InstallGeoLite -ForceDownload

Headless Enrichment

Single CSV:

.\Run-Dibbler.ps1 -NoGui -SourcePath C:\Data\source.csv -OutputPath C:\Data\Enriched -IpColumn ClientIP

Multiple IP columns:

.\Run-Dibbler.ps1 -NoGui -SourcePath C:\Data\proxy.csv -OutputPath C:\Data\Enriched -IpColumn SourceIP,DestinationIP

Generate SQL without executing DuckDB:

.\Run-Dibbler.ps1 -NoGui -SourcePath C:\Data\source.csv -OutputPath C:\Data\Enriched -IpColumn ClientIP -PrepareOnly

Output

Dibbler preserves original source columns and appends enrichment columns for each selected IP field:

• <IpField>_geo_country_iso_code
• <IpField>_geo_country_name
• <IpField>_geo_city_name
• <IpField>_geo_subdivision_name
• <IpField>_geo_latitude
• <IpField>_geo_longitude
• <IpField>_geo_asn
• <IpField>_geo_as_org

AS organization data comes from GeoLite2-ASN.mmdb; there is no separate ASO database file.

By default, output files are written under output/ and use incrementing filenames when a collision exists, such as:

source.enriched.csv
source.enriched_1.csv

Runtime Folders

These folders are local runtime areas and are ignored by Git:

• data/: GeoLite databases.
• logs/: session logs.
• output/: enriched CSV files.
• working/: generated SQL, temporary DuckDB files, downloaded archives.
• tools/duckdb/: downloaded DuckDB executable.

Each runtime directory includes a .gitignore so the folder can exist in the repo without uploading runtime contents.

Working Database Cleanup

Dibbler creates temporary DuckDB database files under working/. Successful runs try to remove .duckdb and .duckdb.wal files automatically.

If Windows still has a transient lock on the files, cleanup is deferred and retried on a later run or through manual cleanup:

.\Run-Dibbler.ps1 -NoGui -CleanWorkingDatabases

To keep working databases for troubleshooting:

.\Run-Dibbler.ps1 -NoGui -SourcePath C:\Data\source.csv -IpColumn ClientIP -RetainWorkingDatabase

The GUI also has Retain working DuckDB files and Clean Working DBs controls.

Configuration

Settings live in config.json. Important fields include:

• app.version
• duckdb.path
• maxmind.countryDatabasePath
• maxmind.cityDatabasePath
• maxmind.asnDatabasePath
• paths.defaultOutputDirectory
• paths.logDirectory
• paths.workDirectory
• processing.overwriteExistingOutput
• processing.defaultIpColumnSuggestions
• processing.retainWorkingDatabases

Config loading merges missing settings with defaults.

Tests

Run the core Pester tests:

Invoke-Pester .\tests\Dibbler.Core.Tests.ps1

The tests are written to work with the older Pester 3 syntax commonly available on Windows analyst VMs.

Development Notes

• Keep GUI/state handling in modules/Dibbler.Gui.psm1.
• Keep testable behavior in modules/Dibbler.Core.psm1.
• Do not commit downloaded databases, outputs, logs, or working files.
• Update CHANGELOG.md and config.json version for functional changes.