# latam-oiv-resolver > Resolver multi-país de operadores de infraestrutura crítica (OIV) para a > América Latina. API unificada e JSON Schema para resolver os equivalentes > a "Operadores de Importancia Vital" (OIV) nos marcos regulatórios LATAM. [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE) [![npm version](https://img.shields.io/badge/npm-v0.1.0--alpha.1-orange.svg)](https://www.npmjs.com/package/latam-oiv-resolver) [![Status](https://img.shields.io/badge/status-alpha-yellow.svg)](#status-v010-alpha1--escopo-piloto) [![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](package.json) [![CI](https://github.com/raceksd-source/latam-oiv-resolver/actions/workflows/ci.yml/badge.svg)](https://github.com/raceksd-source/latam-oiv-resolver/actions/workflows/ci.yml) [![CodeQL](https://github.com/raceksd-source/latam-oiv-resolver/actions/workflows/codeql.yml/badge.svg)](https://github.com/raceksd-source/latam-oiv-resolver/actions/workflows/codeql.yml) Ler em: [English](README.md) · [Español](README.es.md) · **Português (BR)** --- ## Status: `v0.1.0-alpha.1` · escopo piloto > **Não pronto para produção.** Este release é intencionalmente um esqueleto > alpha. Apenas o Chile delega hoje a um resolver verificado em produção. > Os demais países são stubs que documentam as fontes oficiais e convidam > contribuidores locais. | País | Status | Fonte da cobertura | |---|---|---| | Chile (CL) | Estável (via pacote companion) | [`anci-oiv-resolver`](https://github.com/raceksd-source/anci-oiv-resolver) v0.5.0 | | Argentina (AR) | Stub · piloto | Aguardando contribuição | | Brasil (BR) | Stub · piloto (prioritário) | Aguardando contribuição | | Colômbia (CO) | Stub · piloto | Aguardando contribuição | | Uruguai (UY) | Stub · piloto | Aguardando contribuição | | México (MX) | Stub · planejado | Aguardando contribuição | | Peru (PE) | Stub · planejado | Aguardando contribuição | | Equador (EC) | Stub · planejado | Aguardando contribuição | | Costa Rica (CR) | Stub · planejado | Aguardando contribuição | | Panamá (PA) | Stub · planejado | Aguardando contribuição | --- ## Início rápido ```bash npm install latam-oiv-resolver # Opcional · habilita a cobertura ativa do Chile (CL): npm install anci-oiv-resolver ``` ```typescript import { resolveOperator } from 'latam-oiv-resolver'; const operador = await resolveOperator({ country: 'CL', identifier: '97006000-6', razonSocial: 'BANCO DE CRÉDITO E INVERSIONES', }); // → { country: 'CL', domain: 'bci.cl', sector: 'banking_finance', // source: 'companion-package', confidence: 1.0, ... } ``` Veja [`examples/`](examples/) para scripts executáveis. --- ## O que faz - **Normaliza identificadores nacionais** nos diversos formatos tributários e de registro da LATAM (RUT · CNPJ · CPF · RFC · CUIT · NIT · RUC · Cédula Jurídica). - **Resolve operador → domínio canônico** por país, com pontuação de confiança e proveniência explícita (`official-registry` · `companion-package` · `community-curated` · `heuristic` · `stub`). - **Expõe um único JSON Schema** para que cada dataset de país valide contra o mesmo contrato — veja [`data/schema.json`](data/schema.json). - **Não inclui findings, scores CVSS nem inteligência de vulnerabilidades.** O escopo é identificador ↔ operador ↔ domínio. Nada além. --- ## Países suportados | País | Identificador(es) | Referência regulatória | Status | |---|---|---|---| | Chile (CL) | `RUT` | Ley 21.663 · ANCI | Estável (via companion) | | Brasil (BR) | `CNPJ` · `CPF` | PNSI · LGPD (Lei 13.709/2018) · GSI/PR | Stub piloto | | Argentina (AR) | `CUIT` · `CUIL` | Estrategia Nacional de Ciberseguridad | Stub piloto | | Uruguai (UY) | `RUT` (UY) | Marco AGESIC | Stub piloto | | Colômbia (CO) | `NIT` | CONPES 3854 · Ley 2300 · ColCERT | Stub piloto | | México (MX) | `RFC` | LFPDPPP · Sectores Estratégicos | Planejado | | Peru (PE) | `RUC` | DLeg 1412 · Política Nac. Ciberseguridad | Planejado | | Equador (EC) | `RUC` | Política Nacional de Ciberseguridad | Planejado | | Costa Rica (CR) | `Cédula Jurídica` | MICITT · Estrategia Nacional | Planejado | | Panamá (PA) | `RUC` | AIG · Estrategia Nacional | Planejado | Menções genéricas a reguladores nacionais (ANCI · AGESIC · GSI/PR · ColCERT) **não** implicam endosso nem parceria. A fonte da verdade permanece sendo a publicação oficial de cada regulador. --- ## Contribuição prioritária · Brasil Como o mercado brasileiro de cibersegurança é o maior da região, contribuições para `data/countries/br/` têm prioridade. Fontes-alvo iniciais: - **GSI/PR** — Gabinete de Segurança Institucional da Presidência da República - **PNSI** — Política Nacional de Segurança da Informação (Dec. 9.637/2018) - **LGPD** — Lei Geral de Proteção de Dados (Lei 13.709/2018) - **CTIR Gov** — Centro de Tratamento e Resposta a Incidentes Cibernéticos - **ANPD** — Autoridade Nacional de Proteção de Dados Identificadores suportados (esboço inicial): - **CNPJ** · 14 dígitos · `00.000.000/0001-00` - **CPF** · 11 dígitos · `000.000.000-00` (apenas quando aplicável) --- ## Referência da API ### `resolveOperator(input, options?)` ```typescript async function resolveOperator( input: OperatorIdentifier, options?: ResolveOptions ): Promise; ``` | Campo | Tipo | Descrição | |---|---|---| | `input.country` | `LATAMCountry` | ISO 3166-1 alpha-2 (`CL` · `BR` · `MX` · …) | | `input.identifier` | `string` | Identificador nacional em qualquer formatação comum | | `input.razonSocial` | `string?` | Razão social (recomendado para fallback heurístico) | | `options.verify` | `boolean?` | Solicita verificação DNS onde o adaptador suportar | | `options.refresh` | `boolean?` | Força recarga do cache do adaptador (raramente necessário) | Retorna um `ResolvedOperator`: ```typescript interface ResolvedOperator { country: LATAMCountry; identifier: string; // forma normalizada identifierType: IdentifierType; domain: string | null; razonSocial: string | null; sector: LATAMSector; sectorLocal?: string; source: ResolutionSource; confidence: number; // 0–1 verified: boolean | null; note?: string; } ``` ### `resolveBatch(inputs, options?)` ```typescript async function resolveBatch( inputs: OperatorIdentifier[], options?: ResolveOptions ): Promise; ``` Agrupa os inputs por país para carregar cada adaptador apenas uma vez. ### `normalize(country, identifier)` · `isValidIdentifier(country, identifier)` ```typescript import { normalize, isValidIdentifier } from 'latam-oiv-resolver'; normalize('CL', '76.086.428-5'); // → '76086428-5' normalize('BR', '00000000000191'); // → '00.000.000/0001-91' normalize('MX', 'xaxx010101000'); // → 'XAXX010101000' normalize('AR', '30500001735'); // → '30-50000173-5' isValidIdentifier('CL', '97006000-6'); // → true ``` ### `listCountries()` Retorna o array de códigos `LATAMCountry` atualmente expostos pelo pacote (adaptadores implementados mais os stubs piloto). Superfície completa: ver [`src/types.ts`](src/types.ts). --- ## Metodologia `latam-oiv-resolver` opera estritamente sobre **OSINT passivo**. A resolução de domínios usa DNS público (registros A · AAAA · MX) e mapeamentos curados a partir de publicações públicas de reguladores e registros nacionais. Sem varredura ativa, sem acesso não autorizado, sem fontes de dados privadas. As referências à divulgação coordenada de vulnerabilidades se enquadram **conforme os princípios da ISO/IEC 29147:2018** e ISO/IEC 30111:2019. Esses padrões são citados como frameworks de processo, não como declaração de certificação. A metodologia de contribuição por país está documentada em [`docs/METHODOLOGY-LATAM.md`](docs/METHODOLOGY-LATAM.md). A arquitetura e o contrato dos adaptadores em [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md). --- ## Pacote companion A cobertura do Chile (CL) é delegada ao [`anci-oiv-resolver`](https://github.com/raceksd-source/anci-oiv-resolver) v0.5.0, uma implementação de referência mono-país para as 915 entidades designadas sob a Ley 21.663 (registro ANCI). Instale-o como peer dependency opcional para habilitar a resolução ativa de CL: ```bash npm install anci-oiv-resolver ``` Sem o pacote companion, as chamadas a CL caem no adaptador stub (o registro público continua disponível; somente o caminho de resolução muda). --- ## Como contribuir um país Cada país novo requer: 1. **Documentação do marco legal** — `data/countries/{cc}/source.md` 2. **Normalizador de identificador** — `src/normalizers/{tipo}-{cc}.ts` 3. **Adaptador do país** — `src/adapters/{cc}-{regulador}.ts` 4. **Dataset de entidades validado contra JSON Schema** — `data/countries/{cc}/known-domains.json` 5. **Testes unitários + documentação por país** Os datasets de país são mantidos por contribuidores residentes em (ou com expertise verificada em) o marco regulatório daquele país. Veja [`CONTRIBUTING.md`](CONTRIBUTING.md) e o [template de issue para novo país](.github/ISSUE_TEMPLATE/new-country.yml). --- ## Princípios de design 1. **Um JSON Schema, vários países.** Todos os datasets validam contra [`data/schema.json`](data/schema.json). 2. **Apenas fontes públicas.** Cada entrada deve citar uma publicação regulatória ou de registro acessível publicamente. Sem scraping de portais privados. 3. **Curadoria por país.** Um dataset de país é mantido por contribuidores locais com expertise verificada na matéria. 4. **Dados versionados, releases semânticos.** Adicionar um país é um bump `MINOR`, corrigir uma entidade é `PATCH`, mudanças incompatíveis de schema são `MAJOR`. 5. **Alinhado com ISO/IEC 29147:2018 / 30111:2019** como referência de processo. Não é declaração de certificação. --- ## Roadmap - **Q3 2026** — Estabilização do piloto de 5 países (CL estável · AR · UY · BR · CO). - **Q4 2026** — Adicionar MX · PE · EC e publicar `v1.0.0` estável. - **Q1–Q2 2027** — Estender para CR · PA · DO · PY · BO · VE · GT · SV · NI · HN. - **2028+** — 95%+ de cobertura LATAM · cadência anual de atualização alinhada com o ciclo de revisão de cada regulador nacional. Roadmap completo: [`docs/ROADMAP.md`](docs/ROADMAP.md). Governança: [`docs/GOVERNANCE.md`](docs/GOVERNANCE.md). --- ## Licença Apache License 2.0 · ver [LICENSE](LICENSE). --- ## Citação Citação legível por máquina: [`CITATION.cff`](CITATION.cff). ```bibtex @misc{mellafe2026latam, author = {Mellafe Zuvic, David}, title = {latam-oiv-resolver: Multi-country Critical Infrastructure Operator Resolver for Latin America}, year = {2026}, publisher = {GitHub}, version = {v0.1.0-alpha.1}, howpublished = {\url{https://github.com/raceksd-source/latam-oiv-resolver}} } ``` --- ## Mantido por **Reizan** · empresa independente de pesquisa em cibersegurança. Operada através da **AlmaAI SpA** (RUT 78.387.715-5) · La Serena, Chile. Mantenedor: **David Mellafe Zuvic** · [david@reizan.io](mailto:david@reizan.io) ## Segurança Para reportar uma vulnerabilidade de forma privada, ver [SECURITY.md](SECURITY.md).