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.

Ler em: English · Español · 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 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

npm install latam-oiv-resolver
# Opcional · habilita a cobertura ativa do Chile (CL):
npm install anci-oiv-resolver

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/ 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.
• 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?)

async function resolveOperator(
  input: OperatorIdentifier,
  options?: ResolveOptions
): Promise<ResolvedOperator>;

| 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:

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?)

async function resolveBatch(
  inputs: OperatorIdentifier[],
  options?: ResolveOptions
): Promise<ResolvedOperator[]>;

Agrupa os inputs por país para carregar cada adaptador apenas uma vez.

normalize(country, identifier) · isValidIdentifier(country, identifier)

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.

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. A arquitetura e o contrato dos adaptadores em docs/ARCHITECTURE.md.

Pacote companion

A cobertura do Chile (CL) é delegada ao 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:

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 e o template de issue para novo país.

Princípios de design

1. Um JSON Schema, vários países. Todos os datasets validam contra 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. Governança: docs/GOVERNANCE.md.

Licença

Apache License 2.0 · ver LICENSE.

Citação

Citação legível por máquina: CITATION.cff.

@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 · [email protected]

Segurança

Para reportar uma vulnerabilidade de forma privada, ver SECURITY.md.