linebreak-gate

linebreak-gate — o portão de segurança LineBreak na fronteira git/CI

Veja em execução

Uma gravação real, sem simulação: a verificação bloqueia uma CVE crítica com falha fechada, o pin é corrigido, o portão abre.

O ciclo de especificação: um humano nomeado aprova os critérios, check bloqueia até que o critério manual tenha uma aprovação registrada, então tudo passa.

Bloqueia merges que carregam vulnerabilidades conhecidas. Uma ferramenta, dois detectores — a verificação de dependências é gratuita; a revisão de IA é o upgrade Pro:

• Verificação de CVE de dependências — gratuita, sem chave — osv-scanner em todos os ecossistemas (npm, PyPI, Go, Cargo, Maven, …), com um fallback npm audit para projetos npm (cobertura apenas npm e sem dados de versão instalada — a GitHub Action falha fechada se o osv-scanner não puder ser instalado em vez de degradar para ele).
• IA SAST — Pro — uma revisão de segurança por LLM do código-fonte de primeira parte (injeção, autenticação quebrada, exposição de segredos, SSRF, desserialização insegura, uso indevido de criptografia) com verificação adversarial, habilitada por LINEBREAK_LICENSE_KEY (hospedado, usa créditos) ou ANTHROPIC_API_KEY (sua própria chave, tem precedência). Sem uma chave, a verificação de dependências ainda é executada e esta etapa é pulada com um aviso.

O portão bloqueia e pode propor; nunca limpa automaticamente com base na palavra de um agente. Um humano aprova a correção ou registra uma exceção — com um motivo e um aprovador — em um arquivo de auditoria commitado no git.

Este é o mesmo núcleo de verificação que alimenta o restante do portão de segurança dentro do produto LineBreak (o backend desktop importa este pacote), mas é totalmente independente: uma equipe que nunca usou nada mais da LineBreak pode adicionar o portão ao seu repositório e obter aplicação real.

Contribuição e licença. Este repositório é o código-fonte publicado de linebreak-gate (Apache-2.0): cada release chega aqui e no PyPI a partir do nosso CI, e cada mudança passou pelo nosso próprio portão primeiro — verificação de CVE e critérios aprovados por humanos, a mesma disciplina que vendemos. Relatórios de bugs e pedidos de recursos: abra uma issue ou discussão aqui; lemos tudo. PRs diretos para este repositório não podem ser mesclados (releases fluem pelo nosso pipeline de revisão), então comece com uma issue e nós cuidamos do resto.

Início rápido — GitHub Actions

# .github/workflows/security-gate.yml
name: Security gate
on:
  pull_request:

permissions:
  contents: read
  pull-requests: write # for the summary comment

jobs:
  gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: Baktun-Studio/linebreak-gate@v1
        with:
          # fail-on: high # blocking floor; default: critical
          # Optional today; required once license enforcement is enabled.
          license-key: ${{ secrets.LINEBREAK_LICENSE_KEY }}
          # Enables the AI code review; leave unset for dependency scan only.
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}

A action executa linebreak-gate scan, sempre executa report, publica um comentário de PR (atualizado no lugar a cada push, nunca spam), envia o relatório JSON

• artefatos de auditoria como um artefato de workflow, e falha a verificação conforme o código de saída da verificação.

Torne-o uma fronteira real: exija a verificação

Um job de CI que pode ser ignorado é um painel, não um portão. No seu repositório:

Settings → Branches → Branch protection rules → sua branch padrão → "Require status checks to pass before merging" → adicione o job gate (o nome do job que executa esta action). A partir daí, um PR com uma CVE crítica não pode ser mesclado pela interface do GitHub.

Início rápido — qualquer outro CI (exemplo GitLab)

O CLI é um pacote Python simples com códigos de saída estritos — 0 passa, 1 achados bloqueantes, 2 erro de ferramenta/configuração (falha fechada: uma falha do scanner falha o pipeline, nunca é uma aprovação limpa). Qualquer CI que respeite códigos de saída obtém a mesma aplicação:

# .gitlab-ci.yml
security-gate:
  image: python:3.11
  script:
    - pip install linebreak-gate
    - curl -fsSL -o /usr/local/bin/osv-scanner
      "$(curl -fsSL https://api.github.com/repos/google/osv-scanner/releases/latest
      | python -c "import json,sys;print(next(a['browser_download_url'] for a in json.load(sys.stdin)['assets'] if a['name'].endswith('linux_amd64')))")"
    - chmod +x /usr/local/bin/osv-scanner
    - linebreak-gate scan
    - linebreak-gate report

Marque o job como obrigatório (sem allow_failure) e proteja a branch.

O ciclo de especificação — autor, aprove, sirva via MCP, aplique

O portão também aplica critérios de aceitação aprovados, e todo o ciclo é agnóstico de ferramenta — sem conta LineBreak, sem app desktop, sem servidor:

linebreak-gate spec new        # scaffold a draft — fill it with any tool (your
                               # editor, Claude Code, ChatGPT), or distill it
                               # from the PRD you already have in Notion/Jira
linebreak-gate spec approve .linebreak/spec-draft.yml \
  --approver "Ana Lopez <ana@example.com>"   # a human on the record; commits
linebreak-gate mcp install --editor claude-code   # or: cursor · codex

linebreak-gate mcp serve o bundle aprovado (.linebreak/spec/) via MCP (stdio) para Claude Code, Cursor, Codex, ou qualquer cliente MCP. Seis ferramentas: list_stories, get_story (critérios como contexto do agente ANTES do código ser escrito), next_story, set_story_status, check_story (o mesmo motor de avaliação que o CI executa, escopado a uma história), e spec_status (aprovação + estado de assinatura offline). Git é o transporte — sem rede, sem conta, funciona em um clone simples — e nada na ponte pode escrever, editar ou invalidar um critério aprovado: critérios mudam apenas editando o rascunho e re-aprovando, com um humano no registro.

Então linebreak-gate check aplica os mesmos critérios no CI: verificações de máquina executam de verdade, critérios manual bloqueiam até uma aprovação registrada. Primeira execução guiada com o porquê de cada etapa: linebreakapp.com/en/start.

CLI

linebreak-gate init     [--path .] [--fail-on critical|high|medium|low] [--force] [--non-interactive]
linebreak-gate scan     [--path .] [--fail-on critical|high|medium|low] [--format summary|json]
linebreak-gate report   [--path .] [--format summary|json]
linebreak-gate override --finding <id> --reason "…" --approver <name/email> [--path .]
linebreak-gate override --criterion <id> --reason "…" --approver <name/email> [--path .]
linebreak-gate check    [--path .] [--format summary|json]
linebreak-gate signoff  --criterion <id> --approver <name/email> --note "…" [--path .]
linebreak-gate spec new     [--path .] [--out <file>] [--force]
linebreak-gate spec approve <draft> --approver <name/email> [--role architect] [--path .]
linebreak-gate spec list|next [--path .]
linebreak-gate spec show|check <story-id> [--path .]
linebreak-gate mcp      [--path .]            # serve the approved spec over stdio
linebreak-gate mcp install [--editor claude-code|cursor|codex] [--print]
linebreak-gate badge    [--format markdown|html|url]

• init configura um repositório em um comando: escreve o arquivo de workflow (nunca sobrescreve um existente sem --force), opcionalmente escreve .linebreak/gate.yml, oferece armazenar os segredos via GitHub CLI e exigir a verificação gate — e imprime os links de configuração exatos para qualquer coisa que não puder fazer por você.

• scan executa ambos os detectores, escreve artefatos de auditoria nativos do git sob .linebreak/audit/, e sai com 0/1/2.

• report renderiza a verificação registrada: contagens por severidade e cada achado com ID de CVE, CVSS, link do advisory e status de exceção. --format json para máquinas.

• override registra um reconhecimento aprovado por humano de um achado exato — o pacote + versão instalada + tupla CVE. Uma CVE diferente, uma versão alterada ou um novo achado ainda bloqueiam. --reason e --approver são obrigatórios; o registro entra na trilha de aprovação do artefato. Commite o .linebreak/audit/*.json atualizado para que o CI o veja.

• check avalia os critérios de aceitação aprovados (.linebreak/spec/, entregue por spec approve) contra a árvore de trabalho: build/tests/command executam de verdade, manual exige uma aprovação registrada. Sai 0 se tudo satisfeito (ou sem bundle — um no-op limpo), 1 bloqueante (falha ou precisa de aprovação), 2 erro de ferramenta/configuração/bundle (falha fechada). Escreve .linebreak/audit/criteria.json.

• signoff registra uma aprovação humana atribuída para um critério manual sob .linebreak/spec/signoffs/ (aditivo; --approver e --note obrigatórios). Ele se vincula ao critério como aprovado — editar o critério e re-aprovar a especificação torna aprovações anteriores obsoletas. Commite o registro.

• override --criterion registra uma exceção aprovada por humano para um critério de máquina falho em .linebreak/audit/criteria.json — mesma filosofia das exceções de CVE: possível, sempre atribuída, obsoleta uma vez que o critério é editado. Outros critérios bloqueantes ainda bloqueiam.

• spec new / spec approve — o caminho de autoria agnóstico de ferramenta (veja a seção do ciclo de especificação acima): crie um rascunho, preencha com qualquer ferramenta, entregue-o como o bundle aprovado com uma aprovação humana atribuída, commitado. Aprovações locais não assinadas são marcadas identity_source: client; assinaturas criptográficas vêm do serviço de governança (chave de licença).

• spec list imprime o bundle de critérios de aceitação aprovados: cada história, seus critérios com tipos de verificação e a atribuição do aprovador. Somente leitura. Sai 0 em um bundle válido ou quando nenhum existe; sai 2 em um bundle malformado (falha fechada na estrutura). spec next / show / check são os gêmeos CLI das ferramentas da ponte MCP.

Badge

Mostre aos visitantes que o repositório é protegido. linebreak-gate badge imprime um snippet de README pronto para colar (sem chamadas de rede — o badge estático do shields.io é totalmente codificado na URL); --format html|url para as variantes de tag ou URL simples:

[![gated by LineBreak](https://img.shields.io/badge/gated%20by-LineBreak-14120F?labelColor=FAF8F4)](https://www.linebreakapp.com/en/gate)

Configuração — .linebreak/gate.yml

A rigidez do portão é governança, então ela vive no repositório — mudar o limiar é em si um PR: visível, revisável, atribuível no histórico do git.

# .linebreak/gate.yml
fail_on: critical # critical (default) | high | medium | low
exclude_paths: # optional: root-relative globs excluded from scanning
  - fixtures
  - "sandbox/*"
code_scan: auto # auto (run when model credentials are set) | on (required) | off
criteria:
  enforce: true # default: true whenever a spec bundle exists; false disables
  # criteria checking only (the security scan is unaffected)

Precedência: flag --fail-on explícita / input da Action → .linebreak/gate.yml → padrão embutido (critical). Uma configuração inválida é um erro de ferramenta (saída 2) — um arquivo de governança quebrado nunca cai silenciosamente em um padrão.

Registros de auditoria

Cada verificação e cada exceção é registrada em .linebreak/audit/security.json (dependências) e .linebreak/audit/code.json (IA SAST) — o mesmo formato de documento versionado que as ferramentas LineBreak escrevem, carregando achados (ID de CVE, CVSS, link do advisory), motor do scanner, timestamp, ator e a trilha de aprovação com o motivo + aprovador de cada exceção. Quem afrouxou o portão, e quando, é em si auditável.

Preços

Gratuito, para sempre: a verificação de CVE de dependências e todo o ciclo de especificação — autoria, aprovação humana, serviço MCP e aplicação no CI. Sem chave, sem conta.

Pro — US$ 99/mês por equipe (preços): aprovações assinadas criptograficamente e à prova de adulteração (Ed25519, verificáveis offline), modo de aplicação com chave obrigatória e revisão de código de IA hospedada sem chave de API para gerenciar. Compre na página de preços — sua LINEBREAK_LICENSE_KEY chega por e-mail em segundos (é o input license-key da Action). Prefere sua própria chave de modelo? ANTHROPIC_API_KEY também habilita a revisão de IA; a revisão hospedada do Pro é o caminho de configuração zero.

O portão executa aberto por padrão: funciona sem chave e imprime um aviso quando nenhum LINEBREAK_LICENSE_KEY está definido (suprimido para usuários BYOK). Isso é freemium — a verificação de dependências executa gratuitamente. Equipes que querem exigir uma chave Pro válida para o portão executar podem optar por LINEBREAK_ENTITLEMENTS_PROVIDER=remote, que verifica a elegibilidade antes de qualquer verificação e falha fechada em uma chave ausente/inválida/revogada, plano errado ou serviço inacessível — bloqueando todo o portão, incluindo a verificação de dependências.