active_sanction 1.0.0

data/SECURITY.md

@@ -0,0 +1,97 @@
+# Security policy
+
+## Reporting a vulnerability
+
+**Report privately. Do not open a public issue.**
+
+Use GitHub's private vulnerability reporting —
+[**Report a vulnerability**](https://github.com/Babystep-Technologies/active_sanction/security/advisories/new)
+on the Security tab — which opens a draft advisory only you and the maintainers
+can read. If that is unavailable to you, email
+**shen.marshall@gmail.com** with `active_sanction` in the subject.
+
+Please include the version, the Ruby, the source list involved if there is one,
+and the smallest input that reproduces it. A record from a published government
+file is more useful than a synthetic one, and naming the record is not a
+disclosure — it is already public.
+
+## What to expect
+
+This project is maintained by one person, so these are commitments about
+communication rather than about engineering capacity.
+
+| | |
+|---|---|
+| Acknowledgement | within 3 business days |
+| Initial assessment, in scope or not | within 10 business days |
+| Status update while a fix is open | at least every 14 days |
+| Coordinated disclosure window | 90 days by default, negotiable |
+
+A fix ships in a release, with an advisory naming the versions affected and a
+`CHANGELOG.md` entry. **You are credited by name unless you ask not to be.** If
+a report turns out to be a plain bug rather than a vulnerability, we will say so
+and move it to a public issue with your agreement.
+
+## What is in scope
+
+**A screening library that fails to report a listed name is a security
+problem, not merely an inaccuracy.** Somebody may be relying on an empty result
+to clear a payment, and the liability for a missed designation is real. So the
+scope here is wider than it would be for an ordinary library:
+
+- **A systematic screening bypass.** A class of name, a script, a
+  transliteration or a crafted input that reliably evades matching — not one
+  fuzzy score you disagree with, but a shape of input that gets a whole
+  category of listed records past the matcher.
+- **Integrity of a snapshot or a bundle.** Anything that makes the gem accept a
+  modified list as authentic: a signature that verifies when it should not, a
+  checksum that can be satisfied by altered content, a bundle that loads
+  without the verification the caller asked for.
+- **Provenance of a stamped result.** A screening result carries the snapshot
+  checksum, the matcher version and the weights so that a decision can be
+  re-derived years later. Anything that lets a result carry a stamp that does
+  not describe what actually answered it is in scope.
+- **The fetch path.** Redirect handling that can be steered somewhere the
+  publisher did not point, certificate or transport verification that can be
+  downgraded, a cached payload that can be poisoned.
+- **Parsing a hostile file.** Denial of service, memory exhaustion, external
+  entity resolution or file disclosure triggered by a malformed or malicious
+  list, archive or bundle. A government endpoint is a third party, and one that
+  has been compromised serves this library its input.
+- **The storage and cache paths.** Path traversal, a file written outside the
+  directory the host configured, or predictable temporary files.
+- **Leaking a screened name.** Any path by which a subject's name, or the
+  details submitted with it, leaves the host process — a log line, an outbound
+  request, an error message. *No name you screen leaves your process* is a
+  promise this library makes, and a break in it is a vulnerability.
+
+## What is not in scope
+
+- **A single missed record or false alert.** That is match quality. It belongs
+  in a public issue and in
+  [`benchmark/fixtures/labeled_set.yml`](benchmark/fixtures/labeled_set.yml),
+  where it becomes a regression test. The line between this and a systematic
+  bypass is whether the technique generalises; if you are unsure, report it
+  privately and we will sort it out.
+- **A jurisdiction this gem does not cover,** or a list it does not read. The
+  README says which seven ship.
+- **The absence of PEP data, adverse media, beneficial ownership or 50 Percent
+  Rule resolution.** These are documented non-goals, not gaps.
+- **A publisher's own data being wrong,** or a government endpoint being down.
+  Upstream format changes are handled by the canary and belong in a public
+  issue.
+- **Vulnerabilities in the commercial hosted service.** Report those to the
+  same address; they are not tracked in this repository.
+- **Reports generated by a scanner with no working reproduction,** and findings
+  in development-only tooling that never ships in the gem.
+
+## Supported versions
+
+Pre-1.0, only the most recent release receives fixes. There are no backports to
+earlier 0.x versions. Once 1.0 ships, this section will state a support window.
+
+## Dependencies
+
+The gem's runtime dependencies are `csv`, `rexml` and `sorbet-runtime`, all
+pure Ruby. A vulnerability in one of those belongs upstream, but tell us anyway
+if this library's use of it is what makes it reachable — that part is ours.

data/active_sanction.gemspec

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require_relative "lib/active_sanction/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "active_sanction"
+  spec.version       = ActiveSanction::VERSION
+  spec.authors       = ["Marshall Shen"]
+  spec.email         = ["shen.marshall@gmail.com"]
+
+  spec.summary       = "A Ruby toolkit that manages sanction lists around the world."
+  spec.description   = "ActiveSanction fetches government sanctions lists, normalizes them into a single record model, persists them in preferred storage, and screens names against them with explainable fuzzy match scores. Every match carries structured reasons and stamps the snapshot checksum, matcher version, and thresholds so a screening decision can be re-derived during an audit. New sources register through public extension points without forking the gem."
+  spec.homepage      = "https://github.com/Babystep-Technologies/active_sanction"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 3.1"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+
+  spec.metadata["homepage_uri"]    = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/Babystep-Technologies/active_sanction/tree/main"
+  spec.metadata["changelog_uri"]   = "https://github.com/Babystep-Technologies/active_sanction/blob/main/CHANGELOG.md"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  # `csv` and `rexml` are stdlib, not third parties: both shipped inside Ruby
+  # and have since been moved to bundled gems, which means they now have to be
+  # named to be requirable. Declaring them keeps the gem loadable without
+  # changing what it costs a user -- there is still nothing here to compile and
+  # nothing to vendor.
+  #
+  # Nokogiri is deliberately *not* declared. The XML toolkit can drive libxml2
+  # and will if an application asks it to, but a compliance library should not
+  # be the reason a deployment starts building native extensions.
+  spec.add_dependency "csv", "~> 3.3"
+  spec.add_dependency "rexml", "~> 3.3"
+
+  # Sorbet's runtime, and the only piece of the checker that ships. The `sig`
+  # blocks in `lib/` are ordinary method calls, so the library does not load
+  # without it. It is pure Ruby with nothing to compile, which is the rule the
+  # Nokogiri paragraph above is really about. The static half -- `sorbet` and
+  # `tapioca` -- stays in the Gemfile, where a host never sees it.
+  #
+  # It is not free at call time, so the rule is that a signature on a path
+  # which runs per query is declared `.checked(:tests)`: enforced by this
+  # gem's suite and inert in a host's process. The normalizer is the first
+  # such path and carries it throughout; the scorers join it as they land.
+  # A host that wants none of it at all can set
+  # `T::Configuration.default_checked_level = :never` before requiring the gem,
+  # which spec/sorbet_runtime_spec.rb holds us to.
+  spec.add_dependency "sorbet-runtime", "~> 0.6"
+
+  # What ships. Everything tracked in git, minus the parts of this repository
+  # that exist to develop it.
+  #
+  # `spec/` carries the fixtures, which are trimmed copies of government files
+  # and are the largest thing here. `sorbet/` is the checker's working
+  # directory -- its config and the RBIs tapioca generates for our
+  # dependencies. `benchmark/` measures the machine it runs on and answers a
+  # question about this repository, and `canary/` (#69) watches seven
+  # government endpoints on this repository's behalf -- both are here to keep
+  # the library honest, and neither does anything in an application that
+  # installed it. The rest is toolchain: CI, the linter's config, the Rakefile
+  # that drives all of them, and `bin/` -- none of which do anything inside an
+  # installed gem, and each of which is one more file a security scan has to be
+  # told to ignore.
+  #
+  # `site/` (#103) is the documentation site's sources -- an Astro project, a
+  # theme, a link checker and a `node_modules` the moment anybody builds it.
+  # It exists to be published at a URL, and an application that installed this
+  # gem has no use for the machinery that publishes it.
+  #
+  # `AGENTS.md` and `.claude/` (#113) are instructions for a coding agent
+  # working *on* this repository -- which adapter to copy, which gates to run,
+  # which commands reach a government endpoint and must not be run unattended.
+  # They are toolchain in the same sense the Rakefile is, and say nothing to an
+  # application that installed the gem. The leading-dot rule below already
+  # excludes `.claude/`; `AGENTS.md` is named because it sits at the root.
+  #
+  # What is deliberately kept is `docs/`, which is linked from the README and
+  # is as much a part of the library as the code is. That is the whole reason
+  # the site is not built out of `docs/`: doing so would ship an Astro config
+  # and a set of layouts into every application that installs this gem.
+  dev_only = %r{
+    \A(?:
+      (?:test|spec|features|sorbet|benchmark|canary|bin|site|\.github)/ |
+      Gemfile |
+      Rakefile |
+      AGENTS\.md |
+      \.
+    )
+  }x
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(dev_only) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+end