{"id":50181992,"url":"https://github.com/ipanalytics/mmdbpatch","last_synced_at":"2026-05-25T07:05:04.454Z","repository":{"id":359963014,"uuid":"1248181752","full_name":"ipanalytics/MMDBpatch","owner":"ipanalytics","description":"Declarative YAML patching for MaxMind DB files with dry-run diffs and reproducible MMDB overlays.","archived":false,"fork":false,"pushed_at":"2026-05-24T10:12:59.000Z","size":38,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-24T11:31:15.493Z","etag":null,"topics":["asn","cli","data-engineering","fraud-detection","geoip","gitops","go","maxmind","mmdb","networking","security-tools","yaml"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ipanalytics.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-24T09:47:21.000Z","updated_at":"2026-05-24T10:13:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ipanalytics/MMDBpatch","commit_stats":null,"previous_names":["ipanalytics/mmdbpatch"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ipanalytics/MMDBpatch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipanalytics%2FMMDBpatch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipanalytics%2FMMDBpatch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipanalytics%2FMMDBpatch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipanalytics%2FMMDBpatch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ipanalytics","download_url":"https://codeload.github.com/ipanalytics/MMDBpatch/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipanalytics%2FMMDBpatch/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33464014,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-25T06:32:55.349Z","status":"ssl_error","status_checked_at":"2026-05-25T06:32:35.322Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asn","cli","data-engineering","fraud-detection","geoip","gitops","go","maxmind","mmdb","networking","security-tools","yaml"],"created_at":"2026-05-25T07:04:36.145Z","updated_at":"2026-05-25T07:05:04.420Z","avatar_url":"https://github.com/ipanalytics.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MMDBpatch\n\nDeclarative patching for MaxMind DB files. MMDBpatch applies reviewed YAML overlays to existing `.mmdb` databases, producing reproducible patched databases with dry-run diffs suitable for infrastructure, security, fraud/risk, and analytics workflows.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./site/banner.svg\" alt=\"MMDBpatch banner\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/ipanalytics/MMDBpatch/actions/workflows/release.yml\"\u003e\u003cimg alt=\"Release\" src=\"https://img.shields.io/github/actions/workflow/status/ipanalytics/MMDBpatch/release.yml?branch=main\u0026label=release\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/ipanalytics/MMDBpatch/releases\"\u003e\u003cimg alt=\"Version\" src=\"https://img.shields.io/github/v/release/ipanalytics/MMDBpatch?sort=semver\"\u003e\u003c/a\u003e\n  \u003ca href=\"./LICENSE\"\u003e\u003cimg alt=\"License\" src=\"https://img.shields.io/badge/license-Apache%202.0-blue\"\u003e\u003c/a\u003e\n  \u003cimg alt=\"Go\" src=\"https://img.shields.io/badge/go-1.26%2B-00ADD8\"\u003e\n  \u003cimg alt=\"Status\" src=\"https://img.shields.io/badge/status-active-success\"\u003e\n\u003c/p\u003e\n\n---\n\n## Links\n\n| Resource | Location |\n| --- | --- |\n| Repository | [github.com/ipanalytics/MMDBpatch](https://github.com/ipanalytics/MMDBpatch) |\n| Releases | [GitHub Releases](https://github.com/ipanalytics/MMDBpatch/releases) |\n| Example patch | [examples/patches.yaml](./examples/patches.yaml) |\n| Patch schema | [schema/mmdbpatch.schema.json](./schema/mmdbpatch.schema.json) |\n| MaxMind DB writer | [github.com/maxmind/mmdbwriter](https://github.com/maxmind/mmdbwriter) |\n\n## Overview\n\nOperational teams often maintain local corrections and enrichment data for GeoIP, ASN, proxy, risk, or internal network datasets. The usual path is a one-off Go program using `mmdbwriter`, which makes the result hard to review, repeat, and audit.\n\nMMDBpatch turns those corrections into data:\n\n```yaml\n# yaml-language-server: $schema=https://raw.githubusercontent.com/ipanalytics/MMDBpatch/main/schema/mmdbpatch.schema.json\ndefaults:\n  conflict: patch_wins\n\npatches:\n  - cidr: 203.0.113.0/24\n    op: merge\n    set:\n      custom.source: \"manual_override\"\n      custom.risk: \"lab\"\n      geo.country.iso_code: \"DE\"\n\n  - cidr: 198.51.100.0/24\n    op: delete_field\n    field: traits.is_anonymous_proxy\n```\n\nPatch files can live in git, go through code review, run in CI, and be applied during controlled release jobs.\n\n## System Behavior\n\nMMDBpatch reads an existing MaxMind DB, loads a YAML patch document, and applies each operation to the matching network using `mmdbwriter.InsertFunc`.\n\n```mermaid\nflowchart LR\n    A[\"Input MMDB\"] --\u003e C[\"MMDBpatch\"]\n    B[\"YAML patch file\"] --\u003e C\n    C --\u003e D[\"Dry-run diff\"]\n    C --\u003e E[\"Patched MMDB\"]\n    D --\u003e F[\"CI / PR review\"]\n    E --\u003e G[\"Release / deployment\"]\n```\n\nBy default the CLI performs a dry run and prints before/after records for each affected network. Writing a database requires an explicit `-apply` flag and output path.\n\n## Features\n\n| Capability | Description |\n| --- | --- |\n| Declarative patches | YAML operations for CIDR-scoped MMDB changes. |\n| Patch validation | Validate YAML patch files without an input database. |\n| JSON Schema | Editor and CI validation through `schema/mmdbpatch.schema.json`. |\n| Dry-run first | Default mode prints the proposed changes without writing output. |\n| Full affected-network diff | Uses `NetworksWithin` to report affected records under the patched CIDR. |\n| Before/after diff | Human-readable, JSON-lines, or full JSON report output. |\n| Merge semantics | Deep-merge overlay values while preserving unrelated record fields. |\n| Record replacement | Replace selected networks with controlled records. |\n| Field deletion | Remove specific dotted paths from selected records. |\n| Record deletion | Remove selected networks from the database tree. |\n| Conflict strategies | Define behavior for overlapping patch CIDRs. |\n| Reproducible output | Same input database and patch file produce the same patched result. |\n\n## Quick Start\n\n```sh\nmmdbpatch \\\n  -input GeoLite2-City.mmdb \\\n  -patch patches.yaml\n```\n\nApply the patch and write a new database:\n\n```sh\nmmdbpatch \\\n  -input GeoLite2-City.mmdb \\\n  -patch patches.yaml \\\n  -output GeoLite2-City.patched.mmdb \\\n  -apply\n```\n\nEmit machine-readable diff records:\n\n```sh\nmmdbpatch \\\n  -input GeoLite2-City.mmdb \\\n  -patch patches.yaml \\\n  -json\n```\n\nWrite the full report to a JSON file:\n\n```sh\nmmdbpatch \\\n  -input GeoLite2-City.mmdb \\\n  -patch patches.yaml \\\n  -report reports/mmdbpatch.json\n```\n\nValidate a patch file without opening an MMDB:\n\n```sh\nmmdbpatch validate -patch patches.yaml\n```\n\n## Installation\n\nInstall from source:\n\n```sh\ngo install github.com/ipanalytics/MMDBpatch/cmd/mmdbpatch@latest\n```\n\nBuild locally:\n\n```sh\ngit clone https://github.com/ipanalytics/MMDBpatch.git\ncd MMDBpatch\ngo build ./cmd/mmdbpatch\n```\n\nReleased binaries are published for Linux, macOS, and Windows on the [releases page](https://github.com/ipanalytics/MMDBpatch/releases).\n\n## Usage\n\n```text\nUsage of mmdbpatch:\n  -apply\n        write the patched MMDB instead of dry-run only\n  -input string\n        input MMDB path\n  -json\n        print dry-run diff as JSON lines\n  -output string\n        output MMDB path; requires -apply\n  -patch string\n        YAML patch file path\n  -report string\n        write full JSON report to path\n  -version\n        print version information\n```\n\nPatch validation:\n\n```text\nUsage of mmdbpatch validate:\n  -patch string\n        YAML patch file path\n```\n\n### Merge Fields\n\n```yaml\npatches:\n  - cidr: 203.0.113.0/24\n    op: merge\n    set:\n      custom.owner: \"security\"\n      custom.environment: \"lab\"\n      geo.country.iso_code: \"DE\"\n```\n\n### Replace a Record\n\n```yaml\npatches:\n  - cidr: 10.20.30.0/24\n    op: replace\n    set:\n      custom.network: \"corp-vpn\"\n      custom.source: \"netbox\"\n```\n\n### Delete a Field\n\n```yaml\npatches:\n  - cidr: 198.51.100.0/24\n    op: delete_field\n    field: traits.is_anonymous_proxy\n```\n\n### Delete a Record\n\n```yaml\npatches:\n  - cidr: 192.0.2.0/24\n    op: delete_record\n```\n\n## Outputs\n\nMMDBpatch produces three operational artifacts:\n\n| Artifact | Description |\n| --- | --- |\n| Dry-run diff | Before/after records for each affected network, printed to stdout. |\n| JSON report | Complete report written with `-report`, including summary counters and changed fields. |\n| Patched MMDB | New MaxMind DB file written only when `-apply` and `-output` are set. |\n\nExample human-readable dry-run output:\n\n```text\nmerge 203.0.113.0/24\n  before: {\"geo\":{\"country\":{\"iso_code\":\"US\"}}}\n  after:  {\"custom\":{\"risk\":\"lab\",\"source\":\"manual_override\"},\"geo\":{\"country\":{\"iso_code\":\"DE\"}}}\npatches: 1, applied: 1, skipped: 0, affected_networks: 1, changed_networks: 1\n```\n\nExample JSON-lines output:\n\n```json\n{\"cidr\":\"203.0.113.0/24\",\"network\":\"203.0.113.0/24\",\"op\":\"merge\",\"changed\":true,\"fields_changed\":[\"custom.risk\",\"custom.source\",\"geo.country.iso_code\"],\"before\":{\"geo\":{\"country\":{\"iso_code\":\"US\"}}},\"after\":{\"custom\":{\"risk\":\"lab\",\"source\":\"manual_override\"},\"geo\":{\"country\":{\"iso_code\":\"DE\"}}}}\n```\n\nExample report summary:\n\n```json\n{\n  \"total\": 2,\n  \"applied\": 2,\n  \"skipped\": 0,\n  \"affected_networks\": 2,\n  \"changed_networks\": 2,\n  \"fields_changed\": [\n    \"custom.source\",\n    \"geo.country.iso_code\",\n    \"traits.is_anonymous_proxy\"\n  ]\n}\n```\n\n## Patch Format\n\nTop-level document:\n\n```yaml\n# yaml-language-server: $schema=https://raw.githubusercontent.com/ipanalytics/MMDBpatch/main/schema/mmdbpatch.schema.json\ndefaults:\n  conflict: patch_wins\n\npatches:\n  - cidr: 203.0.113.0/24\n    op: merge\n    set:\n      path.to.field: value\n```\n\nSupported operations:\n\n| Operation | Required fields | Behavior |\n| --- | --- | --- |\n| `merge` | `cidr`, `set` | Deep-merges `set` into the existing MMDB record. |\n| `replace` | `cidr`, `set` | Replaces the record for the CIDR with `set`. |\n| `delete_field` | `cidr`, `field` | Deletes one dotted field path from the existing record. |\n| `delete_record` | `cidr` | Removes the record for the CIDR. |\n\nConflict strategies:\n\n| Strategy | Behavior |\n| --- | --- |\n| `patch_wins` | Apply patches in file order. Later overlapping patches can refine earlier ranges. |\n| `first_wins` | Apply the first patch for an overlapping range and skip later overlapping patches. |\n| `fail_on_overlap` | Reject the patch file when two patch CIDRs overlap. |\n\nSet a default for the patch file:\n\n```yaml\ndefaults:\n  conflict: fail_on_overlap\n```\n\nOverride it for a single patch:\n\n```yaml\npatches:\n  - cidr: 203.0.113.0/24\n    op: merge\n    conflict: patch_wins\n    set:\n      custom.source: \"manual_override\"\n```\n\nField paths are dot-separated:\n\n```yaml\nset:\n  geo.country.iso_code: \"DE\"\n```\n\nThe path above expands to:\n\n```json\n{\n  \"geo\": {\n    \"country\": {\n      \"iso_code\": \"DE\"\n    }\n  }\n}\n```\n\nNested YAML maps are accepted when they are a better fit for the data.\n\n## Operational Notes\n\n- Treat patch files as release artifacts. Review them the same way you review firewall, routing, detection, or enrichment changes.\n- Keep source MMDB checksums with release metadata when reproducibility matters.\n- Run dry-run mode in pull requests and deployment previews.\n- Use `mmdbpatch validate` in pre-commit hooks and CI jobs.\n- Write patched databases to a new path and promote them through the same rollout mechanism used for the original database.\n- Use JSON-lines diff output when integrating with CI logs, artifact storage, or approval systems.\n- Store full `-report` JSON artifacts for audit trails when overrides affect production datasets.\n\n## Use Cases\n\n| Team | Example |\n| --- | --- |\n| Security engineering | Override risk metadata for lab, VPN, Tor, proxy, and partner ranges. |\n| Fraud/risk | Attach internal scoring tags to high-signal prefixes. |\n| Infrastructure | Correct geolocation for office, datacenter, and private interconnect ranges. |\n| Analytics | Add stable internal dimensions used by pipelines and dashboards. |\n| Data engineering | Keep enrichment patches versioned and reproducible across environments. |\n\n## Project Scope\n\nMMDBpatch focuses on deterministic patching of existing MaxMind DB files. It is intended to be small, auditable, and easy to run in CI.\n\nIn scope:\n\n- reading an existing `.mmdb`\n- applying CIDR-scoped declarative patch operations\n- producing reviewable diffs\n- writing a patched `.mmdb`\n- supporting automation-friendly output\n\nOut of scope:\n\n- collecting GeoIP, ASN, proxy, VPN, or threat intelligence data\n- replacing dataset providers\n- operating a hosted enrichment service\n- maintaining a central registry of overrides\n\n## Limitations\n\n- Diff reporting follows MaxMind DB network iteration behavior. When a patch CIDR is contained by a larger database network, the containing network is reported as the affected source record.\n- Conflict strategies apply to overlapping patch CIDRs. They do not attempt to infer business ownership of fields inside a record.\n- Output compatibility depends on the input database structure and reader expectations for that database type.\n\n## Directory Structure\n\n```text\n.\n├── cmd/mmdbpatch/          # CLI entrypoint\n├── examples/               # Example patch files\n├── internal/patch/         # Patch parser, diff logic, and MMDB mutation engine\n├── schema/                 # JSON Schema for patch files\n├── site/                   # Repository visual assets\n├── .github/workflows/      # CI and release automation\n├── .github/actions/        # Reusable local GitHub Actions\n├── go.mod\n├── LICENSE\n└── README.md\n```\n\n## Deployment\n\nMMDBpatch is designed for CI/CD pipelines that already distribute MMDB artifacts.\n\nTypical release job:\n\n```sh\nmmdbpatch \\\n  -input vendor/GeoLite2-City.mmdb \\\n  -patch overlays/production.yaml \\\n  -output dist/GeoLite2-City.production.mmdb \\\n  -apply\n```\n\nRecommended pipeline stages:\n\n| Stage | Action |\n| --- | --- |\n| Validate | Parse patch file and run dry-run diff. |\n| Review | Store diff output as a CI artifact or PR comment. |\n| Build | Apply patch to a pinned input database. |\n| Verify | Run downstream lookup checks against known prefixes. |\n| Promote | Publish the patched MMDB through existing artifact rollout. |\n\n### GitHub Actions\n\nThis repository includes a local validation action:\n\n```yaml\n- uses: ipanalytics/MMDBpatch/.github/actions/validate@v0.1.0\n  with:\n    patch: overlays/production.yaml\n```\n\nFor repository-local checks, the included CI workflow validates `examples/patches.yaml`, runs tests, and runs `go vet`.\n\n\u003cdetails\u003e\n\u003csummary\u003eRelease workflow\u003c/summary\u003e\n\nThis repository includes a GitHub Actions workflow that builds release binaries for Linux, macOS, and Windows when a `v*` tag is pushed.\n\n```sh\ngit tag v0.1.0\ngit push origin v0.1.0\n```\n\nThe workflow creates checksums and attaches archives to the GitHub release.\n\n\u003c/details\u003e\n\n## License\n\nApache License 2.0. See [LICENSE](./LICENSE).\n\n## Disclaimer\n\nMMDBpatch modifies databases supplied by the operator. Validate patched output against your deployment requirements before promotion.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fipanalytics%2Fmmdbpatch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fipanalytics%2Fmmdbpatch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fipanalytics%2Fmmdbpatch/lists"}