openasn 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f423b3d573d4d10e9062c210b0f1704520518dd0984beb6229092c36aa18c91
-  data.tar.gz: e9c15ca9d880ee0a2fd762c9b7253bfd5bbe92e50b990ac62191ab3cae59b5eb
+  metadata.gz: 9fcde0e4605b2400824b5e03518b626465621cf43418d647a5b55d937cd66f38
+  data.tar.gz: beeee7a904311dd4a796c3e8b6306344b92e12d3410d5393dbc15bb3f56e9b02
 SHA512:
-  metadata.gz: a269180e3fd9f820e2a24f1ae0f5747fd610c4cc81a2e0b09439970cecba931c4059e3ca21fac194b271709532d40a44cdfc9345ce2c19a48891b36b93401775
-  data.tar.gz: cc2a87918a1869b661fc5624c36779e0a33ee98c7ba3db9d35686469ab9a7622ebeae77e8d77a6f4e71dc9ef0801c4c00854f32beb9e211726f8b2957463e25f
+  metadata.gz: 659b36d6540e8e625e665c8030cc99c73c2c0ff832270a206e4096d2a2ec5ee3428423dca27cf689f0af30606612dc51a9dbf5858400ecc8f5dd91af7fff88b0
+  data.tar.gz: be56f2a505e3c127ae65f1caed99f1aadcdf521a7d94e426f82a3a20e9bd8871e5478148905830a1bb01852c327b993462079829228e306f953d4906a69dcc20

data/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## [0.3.1] - 2026-07-07
+
+### Fixed
+
+- `rails generate openasn:install` now inserts `OpenASN::UpdateJob` under an
+  existing `production:` entry in `config/recurring.yml` instead of appending
+  a duplicate top-level key that can make YAML parsers drop existing jobs.
+- README scheduling guidance now calls out that manual update jobs should run
+  after the 03:17 UTC data build, using UTC to avoid daylight-saving drift.
+- Removed the top-level `rexml/document` require from the WLVPN Tier B parser
+  so production Ruby 3.4 bundles that exclude the `rexml` bundled gem can boot
+  and precompile assets without adding app-side dependencies.
+
+## [0.3.0] - 2026-07-07
+
+Ergonomics release, driven by dogfooding the analytics/enrichment use case
+(surfacing IP origin in admin panels) in a production Rails app.
+
+### Added
+
+- `Result#label` — the verdict as a short human-readable string
+  ("Residential ISP", "Hosting / datacenter", "Privacy relay") for admin
+  tables, tooltips, and log lines. One label per verdict, same append-only
+  contract as the enum.
+- `Result#flag_names` — the ASN-level flag bitfield decoded to symbols
+  (`[:bad_asn, :vpn_provider]`), plus `Result#flag?(name)` and
+  `Result#bad_asn?` sugar. No more bit arithmetic to answer "is this ASN in
+  bad-asn-list?".
+- `OpenASN.try_lookup(ip)` — nil-safe lookup: returns `nil` on nil/blank/
+  unparseable input instead of raising. The right call site for views and
+  analytics over historical data, where a garbage IP is data, not an
+  exception.
+- `Result#to_h` now includes `flag_names` (append-only key addition; the
+  raw `flags` integer was useless in a log line).
+
+### Changed
+
+- README reframed analytics-first: enriching admin panels/audit trails is
+  the primary documented use case; acting on the signal (step-up
+  verification, rate limits) is the optional later step.
+
 ## [0.2.0] - 2026-07-06
 
 ### Added
@@ -48,5 +89,7 @@
   ranges, provider-attributed VPN overlays), Rack middleware, Rails install
   generator.
 
+[0.3.1]: https://github.com/openasn/openasn-ruby/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/openasn/openasn-ruby/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/openasn/openasn-ruby/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/openasn/openasn-ruby/releases/tag/v0.1.0

data/README.md

@@ -11,6 +11,7 @@
 result = OpenASN.lookup(request.remote_ip)
 
 result.verdict          # => :residential_isp
+result.label            # => "Residential ISP" — human-readable, for admin UIs & logs
 result.infrastructure?  # => false  (true only for :hosting / :vpn / :tor_exit)
 result.likely_human?    # => true   (:residential_isp, :mobile, :relay, :cgnat, :enterprise_gateway)
 result.asn              # => 3352
@@ -18,10 +19,10 @@ result.as_org           # => "TELEFONICA DE ESPANA S.A.U."
 result.sources          # => [:asn_category]  — every verdict is auditable
 ```
 
-It's the missing first line of defense for signups, checkouts, and abuse-prone endpoints: the signal that today costs $79–$200/month from commercial IP-intelligence APIs, as free, open, auditable data — compiled nightly from legally clean sources by the [OpenASN data project](https://github.com/openasn/openasn), with a data seed bundled right in the gem so it works on first boot, offline.
+It answers, at zero marginal cost, the question every product eventually asks: **where do my signups, logins, and checkouts actually come from?** Enrich your admin panel, analytics, and audit trails with network origin — and if you ever decide to *act* on the signal, the same verdict drives step-up verification or rate limits. It's the data that costs $79–$200/month from commercial IP-intelligence APIs, as free, open, auditable data — compiled nightly from legally clean sources by the [OpenASN data project](https://github.com/openasn/openasn), with a data seed bundled right in the gem so it works on first boot, offline.
 
 > [!IMPORTANT]
-> **What this is NOT.** A clean or `:residential_isp` verdict is **absence of evidence, not proof of innocence**. Residential proxies — malicious traffic exiting through real home IPs — are structurally hard to detect offline, and OpenASN does not claim to detect them. `:vpn`, `:hosting`, and `:tor_exit` are high-confidence; treat everything else as a signal, not a sentence. **Never hard-block `:relay`, `:cgnat`, or `:mobile` — those are real people.** OpenASN is a first line of defense, not a fraud engine.
+> **What this is NOT.** A clean or `:residential_isp` verdict is **absence of evidence, not proof of innocence**. Residential proxies — malicious traffic exiting through real home IPs — are structurally hard to detect offline, and OpenASN does not claim to detect them. `:vpn`, `:hosting`, and `:tor_exit` are high-confidence; treat everything else as a signal, not a sentence. **Never hard-block `:relay`, `:cgnat`, or `:mobile` — those are real people.** OpenASN tells you what the network *is*; it is not a fraud engine, and a verdict is a fact to weigh, never a sentence to execute.
 
 ## How it works
 
@@ -58,6 +59,11 @@ rails generate openasn:install
 
 The generator creates `config/initializers/openasn.rb` (documented defaults) and, if you're on Solid Queue, schedules the daily `OpenASN::UpdateJob` in `config/recurring.yml`. **No migrations, no database** — data lives in `storage/openasn/` as memory-mapped-style packed files.
 
+If you wire the job yourself, schedule it after the OpenASN data build
+publishes at **03:17 UTC**. The generator uses `every day at 4:12am UTC` on
+purpose; local time zones with daylight saving can drift before the UTC build
+and fetch yesterday's release.
+
 Not on Rails? `OpenASN.lookup` works anywhere Ruby ≥ 3.1 runs; schedule `OpenASN.update!` daily with cron/whenever.
 
 ## The API
@@ -68,9 +74,14 @@ Not on Rails? `OpenASN.lookup` works anywhere Ruby ≥ 3.1 runs; schedule `OpenA
 r = OpenASN.lookup("146.70.107.100")   # aliases: OpenASN.check, OpenASN.[]
 # Never nil. Raises OpenASN::InvalidIPError (an ArgumentError) on garbage input.
 
+r = OpenASN.try_lookup(user.signup_ip) # nil-safe variant: nil/blank/garbage in,
+                                       # nil out — right for views and analytics
+                                       # over historical data
+
 r.verdict         # one of: :residential_isp :mobile :business :hosting :vpn
                   #         :tor_exit :relay :enterprise_gateway :education
                   #         :government :cgnat :private :unknown
+r.label           # "VPN" — the verdict as a short human-readable string
 r.infrastructure? # :hosting | :vpn | :tor_exit — the honest, high-confidence boolean
 r.likely_human?   # :residential_isp | :mobile | :relay | :cgnat | :enterprise_gateway
 r.vpn? r.hosting? r.tor? r.relay? r.mobile? r.private? r.cgnat?
@@ -81,6 +92,9 @@ r.category        # "hosting"          (raw upstream category)
 r.network_role    # "major_transit"    (raw upstream routing role)
 r.provider        # "aws" | "ProtonVPN" | "iCloud Private Relay" | nil (overlay attribution)
 r.sources         # [:x4b_vpn] — which data layer decided; every verdict is auditable
+r.flag_names      # [:vpn_provider, :bad_asn] — ASN-level signals, decoded to names
+r.bad_asn?        # ASN is in brianhama/bad-asn-list (infrastructure signal, not an accusation)
+r.flag?(:cdn)     # named check for any flag in r.flag_names' vocabulary
 r.context_flags   # [:cloudflare_range] — context that never decides verdicts
 r.unrouted?       # true when no ASN announces this IP
 r.flags           # raw u16 for power users (see the data project's FORMAT.md)
@@ -103,13 +117,14 @@ OpenASN returns one object, but its fields answer different questions:
 | `sources` | Which rule/data layer decided the verdict | Best debugging field. Log it. |
 | `provider` | Provider attribution from an exact overlay hit (`"aws"`, `"azure"`, `"ProtonVPN"`, ...) | Display/log it when present; nil is normal. |
 | `context_flags` | Extra context that never decides the verdict | Useful for policy experiments; do not block solely on it. |
-| `flags` | Packed low-level artifact bits | Power-user/debug field; prefer `verdict` and `sources` in app code. |
+| `flag_names` | ASN-level signals, decoded (`:bad_asn`, `:vpn_provider`, `:mobile_carrier`, `:enterprise_gw`, `:cdn`, `:hosting_extra`) | Display/log them; `bad_asn?` and `flag?(:name)` are the sugar. |
+| `flags` | Packed low-level artifact bits | Wire detail; prefer `flag_names` in app code. |
 
 Common examples:
 
 - A DIGI Spain home IP is usually `category: "isp"` and `verdict: :residential_isp`. That is expected: `category` describes the ASN; `verdict` is OpenASN's safer application-level label.
 - An Amazon IP may be `category: "hosting"`, `sources: [:x4b_dc]`, and with Tier B enabled `provider: "aws"`. The verdict remains `:hosting`; Tier B only improves attribution.
-- `bad_asn` is not an accusation and not a verdict. It means the ASN appears in `brianhama/bad-asn-list`, a curated MIT-licensed hosting/cloud/colo ASN list. When that bit decides classification, `sources` includes `:asn_bad_asn`.
+- `bad_asn?` is not an accusation and not a verdict. It means the ASN appears in `brianhama/bad-asn-list`, a curated MIT-licensed hosting/cloud/colo ASN list. When that signal decides classification, `sources` includes `:asn_bad_asn`.
 - `:residential_isp` means "known eyeball ISP, no stronger infrastructure signal found." It does **not** mean "safe user."
 
 ### Verdict cheat sheet
@@ -179,12 +194,16 @@ request.env["openasn.result"]&.infrastructure?
 > [!WARNING]
 > **The classic integration bug:** behind a proxy/CDN without trusted-proxy configuration, you'll classify your own load balancer on every request (everything comes back `:private` or your host's datacenter). Inside Rails the middleware uses `remote_ip` semantics (honors `config.action_dispatch.trusted_proxies`); make sure the real client IP reaches your app — e.g. with the `cloudflare-rails` gem when behind Cloudflare.
 
-## Recommended rollout: shadow mode first
+## Recommended rollout: enrich first, act later (maybe never)
 
-Log for two weeks. Then decide. (This is how we dogfood it.)
+Start where the value is certain and the risk is zero: **visibility**. Put the verdict next to every IP your team already looks at. For many apps that's the whole integration — and it's how we dogfood it ourselves.
 
 ```ruby
-# 1. SHADOW — measure, block nothing:
+# 1. ENRICH — pure analytics, blocks nothing, breaks nothing:
+#    surface origin in your admin panel and audit trails…
+OpenASN.try_lookup(user.signup_ip)&.label   # "Residential ISP" / "VPN" / "Hosting / datacenter"
+
+#    …and/or log it on the flows you care about:
 class RegistrationsController < ApplicationController
   def create
     Rails.logger.info(openasn: OpenASN.lookup(request.remote_ip).to_h.merge(flow: "signup"))
@@ -192,8 +211,9 @@ class RegistrationsController < ApplicationController
   end
 end
 
-# 2. Weeks later, with YOUR false-positive data in hand, act — prefer
-#    step-up verification (email confirm, captcha, phone) over hard blocks:
+# 2. If (and only if) your OWN data says you have an abuse problem worth the
+#    friction, act — prefer step-up verification (email confirm, captcha,
+#    phone) over hard blocks:
 Rack::Attack.blocklist("openasn: infrastructure on signup") do |req|
   req.post? && req.path == "/signup" && OpenASN.lookup(req.ip).infrastructure?
 end

data/lib/generators/openasn/install/install_generator.rb

@@ -12,6 +12,14 @@ module Openasn
     class InstallGenerator < Rails::Generators::Base
       source_root File.expand_path("templates", __dir__)
 
+      RECURRING_JOB = <<~YAML
+        # Added by `rails g openasn:install` — daily IP-origin data refresh
+        openasn_update:
+          class: OpenASN::UpdateJob
+          queue: default
+          schedule: every day at 4:12am UTC
+      YAML
+
       def create_initializer
         template "openasn.rb", "config/initializers/openasn.rb"
       end
@@ -30,15 +38,8 @@ module Openasn
 
         # 4:12am UTC: after the nightly data build (03:17 UTC) completes,
         # off-hour to be kind to the Tier B upstreams.
-        append_to_file recurring, <<~YAML
-
-          # Added by `rails g openasn:install` — daily IP-origin data refresh
-          production:
-            openasn_update:
-              class: OpenASN::UpdateJob
-              queue: default
-              schedule: every day at 4:12am UTC
-        YAML
+        recurring_path = File.expand_path(recurring, destination_root)
+        File.write(recurring_path, recurring_with_openasn_job(File.read(recurring_path)))
       end
 
       def display_post_install_message
@@ -63,6 +64,27 @@ module Openasn
         say "     and :relay/:cgnat/:mobile are real humans — never hard-block them.", :yellow
         say ""
       end
+
+      private
+
+      def recurring_with_openasn_job(contents)
+        production = contents.match(/^production:\s*$/)
+        return "#{contents.rstrip}\n\nproduction:\n#{indent(RECURRING_JOB, 2)}" unless production
+
+        insert_at = next_environment_index(contents, production.end(0)) || contents.length
+        "#{contents[0...insert_at].rstrip}\n\n#{indent(RECURRING_JOB, 2)}#{contents[insert_at..]}"
+      end
+
+      def next_environment_index(contents, offset)
+        tail = contents[offset..]
+        match = tail.match(/\n(?=\S[^:\n]*:\s*$)/)
+        match && offset + match.begin(0)
+      end
+
+      def indent(text, spaces)
+        prefix = " " * spaces
+        text.lines.map { |line| line == "\n" ? line : "#{prefix}#{line}" }.join
+      end
     end
   end
 end

data/lib/generators/openasn/install/templates/openasn.rb

@@ -18,7 +18,7 @@ OpenASN.configure do |config|
 
   # Self-host or pin the data source if you need to:
   # config.release_url = "https://github.com/openasn/openasn/releases/download/latest/"
-  # config.pin_version = "2026-07-04"   # a dated release tag, for reproducible builds
+  # config.pin_version = "v2026.07.04"  # a dated release tag, for reproducible builds
 
   # Tier B overlays — fetched by YOUR server from the original authorities
   # (Apple, Tor Project, AWS…), per the project's fetch-manifest. Defaults:

data/lib/openasn/parsers.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "json"
-require "rexml/document"
 require "zlib"
 
 module OpenASN
@@ -219,13 +218,11 @@ module OpenASN
     end
 
     register "wlvpn_server_list_xml" do |body|
-      doc = REXML::Document.new(body)
-      tokens = []
-      doc.elements.each("//server") do |server|
-        next unless server.attributes["visible"].to_s == "1" && server.attributes["status"].to_s == "1"
+      tokens = xml_tag_attributes(body, "server").filter_map do |attrs|
+        next unless attrs["visible"].to_s == "1" && attrs["status"].to_s == "1"
 
-        ip = server.attributes["ip"].to_s.strip
-        tokens << ip unless ip.empty?
+        ip = attrs["ip"].to_s.strip
+        ip unless ip.empty?
       end
       raise ParseError, "wlvpn_server_list_xml: no visible active server IPs — schema changed?" if tokens.empty?
 
@@ -433,6 +430,20 @@ module OpenASN
                 .strip
       end
 
+      # Tiny tag-attribute scanner for provider XML-ish feeds. We only need
+      # exact attributes from a trusted source-specific tag; pulling in REXML
+      # would make production apps depend on a bundled gem that Ruby 3.4 no
+      # longer guarantees is installed.
+      def xml_tag_attributes(body, tag_name)
+        body.scan(/<#{Regexp.escape(tag_name)}\b[^>]*>/i).map do |tag|
+          attrs = {}
+          tag.scan(/\b([a-z_:][\w:.-]*)\s*=\s*(["'])(.*?)\2/im).each do |key, _quote, value|
+            attrs[key.downcase] = value
+          end
+          attrs
+        end
+      end
+
       def openvpn_remote_hosts(content)
         content.each_line.filter_map do |line|
           match = line.match(/\Aremote\s+([^\s]+)(?:\s|$)/i)

data/lib/openasn/result.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "binary_format"
+
 module OpenASN
   # The answer to "where is this IP really coming from?". Immutable.
   #
@@ -31,8 +33,29 @@ module OpenASN
     # app decides those.
     LIKELY_HUMAN_VERDICTS = %i[residential_isp mobile relay cgnat enterprise_gateway].freeze
 
+    # Short human-readable names for every verdict — what you'd print in an
+    # admin table or a log line a human reads. Deliberately neutral wording
+    # (no "suspicious", no "risky"): the label states what the network IS;
+    # what to do about it is your app's policy. Keys follow the VERDICTS
+    # append-only contract.
+    LABELS = {
+      residential_isp: "Residential ISP",
+      mobile: "Mobile carrier",
+      business: "Business",
+      hosting: "Hosting / datacenter",
+      vpn: "VPN",
+      tor_exit: "Tor exit",
+      relay: "Privacy relay",
+      enterprise_gateway: "Corporate gateway",
+      education: "University / research",
+      government: "Government",
+      cgnat: "Carrier NAT",
+      private: "Private IP",
+      unknown: "Unknown"
+    }.freeze
+
     attr_reader :ip, :verdict, :asn, :as_org, :category, :network_role,
-                :provider, :sources, :flags, :context_flags
+                :provider, :sources, :flags, :context_flags, :flag_names
 
     def initialize(ip:, verdict:, asn: nil, as_org: nil, category: nil,
                    network_role: nil, provider: nil, sources: [], flags: 0,
@@ -46,14 +69,30 @@ module OpenASN
       @provider = provider
       @sources = sources.freeze
       @flags = flags
+      # The raw u16 is a wire detail; apps want names. Decoded once here so
+      # nobody downstream needs BinaryFormat bit knowledge.
+      @flag_names = BinaryFormat.flag_names(flags).freeze
       @context_flags = context_flags.freeze
       @unrouted = unrouted
       freeze
     end
 
+    # The verdict as a short human-readable string ("Residential ISP",
+    # "Hosting / datacenter") — for admin tables, tooltips, log lines.
+    def label = LABELS.fetch(verdict)
+
     def infrastructure? = INFRASTRUCTURE_VERDICTS.include?(verdict)
     def likely_human?   = LIKELY_HUMAN_VERDICTS.include?(verdict)
 
+    # Named ASN-level flag check: flag?(:bad_asn), flag?(:cdn), … (the full
+    # vocabulary is BinaryFormat::FLAG_NAMES.values / the README table).
+    def flag?(name) = flag_names.include?(name)
+
+    # The ASN appears in brianhama/bad-asn-list — a curated catalog of
+    # hosting/cloud/colo ASNs. An infrastructure signal worth an admin's
+    # glance, NOT a verdict override and NOT a claim of abuse.
+    def bad_asn? = flag?(:bad_asn)
+
     def vpn?     = verdict == :vpn
     def hosting? = verdict == :hosting
     def tor?     = verdict == :tor_exit
@@ -67,6 +106,7 @@ module OpenASN
 
     # Everything, for logging and shadow mode. Stable keys — CarHey-style
     # shadow analyses depend on this shape staying append-only.
+    # (flag_names added in 0.3.0: the raw bitfield is useless in a log line.)
     def to_h
       {
         ip: ip,
@@ -80,6 +120,7 @@ module OpenASN
         provider: provider,
         sources: sources,
         flags: flags,
+        flag_names: flag_names,
         context_flags: context_flags,
         unrouted: unrouted?
       }

data/lib/openasn/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OpenASN
-  VERSION = "0.2.0"
+  VERSION = "0.3.1"
 end

data/lib/openasn.rb

@@ -72,6 +72,18 @@ module OpenASN
     alias check lookup
     alias [] lookup
 
+    # Like lookup, but returns nil on nil/blank/unparseable input instead of
+    # raising — for analytics and rendering call sites where a missing or
+    # garbage IP is ordinary data (an old DB row, a stripped header), not an
+    # exceptional condition worth a begin/rescue at every call site.
+    def try_lookup(ip)
+      return nil if ip.nil? || (ip.is_a?(String) && ip.strip.empty?)
+
+      lookup(ip)
+    rescue InvalidIPError
+      nil
+    end
+
     # Refresh canonical artifacts + Tier B overlays now, atomically
     # swapping the in-memory dataset on success.
     # -> :updated | :tier_b_only | :unchanged | :locked

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: openasn
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.1
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-07-06 00:00:00.000000000 Z
+date: 2026-08-08 00:00:00.000000000 Z
 dependencies: []
 description: 'OpenASN classifies where an IP address is really coming from — residential
   ISP, mobile carrier, hosting/datacenter, VPN, Tor exit, iCloud Private Relay, enterprise