oss-analyzer

Suíte de análise de código 100% Open Source (segurança e conformidade) para CI do GitLab e GitHub Actions — SCA, SAST, segredos e licenças, orientada por uma única política versionada. Repositórios poliglotas (Go, Rust, Java/JVM, Python, JS/TS, C/C++). Sem SaaS, nenhum código enviado a terceiros.

Primeiros passos

O oss-analyzer controla um repositório com base na sua segurança e conformidade em CI: ele executa os scanners, aplica uma política versionada e fornece um veredito, com um dashboard HTML e relatórios de merge request.

flowchart LR
    repo["Your repository"]
    subgraph checks["Scanners: they collect, never block"]
        deps["Dependencies<br/>Syft SBOM<br/>Grype, OSV-Scanner"]
        licenses["Licenses<br/>license gate on the SBOM<br/>policy-licenses.yml"]
        code["Code<br/>Semgrep<br/>policy-semgrep.yml"]
        secrets["Secrets<br/>Gitleaks, whole git history<br/>policy-gitleaks.toml"]
        iac["Dockerfiles, IaC<br/>Trivy"]
        headers["SPDX headers<br/>REUSE"]
    end
    policy{{"Policy<br/>thresholds, modes, exceptions<br/>policy-global.yml"}}
    verdict(["One verdict: pass or block<br/>dashboard, merge request reports"])

    repo --> deps & licenses & code & secrets & iac & headers --> policy --> verdict

Os arquivos policy-* são as suas configurações, na sua pasta security/: cada um é opcional e complementa os padrões do oss-analyzer (consulte Personalizando o oss-analyzer).

Cada achado acaba num único dashboard, aqui num projeto de demonstração deliberadamente vulnerável (590 achados, 333 deles bloqueantes):

Três formas de o executar, com a mesma política e o mesmo relatório:

Componente GitLab CI/CD

include:
  - component: gitlab.com/thalesgroup/oss-analyzer/[email protected]

Isso é tudo, no gitlab.com: o componente é publicado em seu Catálogo de CI/CD a partir de gitlab.com/thalesgroup/oss-analyzer, uma cópia somente leitura deste repositório. Em uma instância auto-gerenciada, que só pode incluir seus próprios projetos, espelhe esse projeto lá e inclua-o pelo seu caminho na sua instância; sua imagem permanece em registry.gitlab.com/thalesgroup/oss-analyzer (OSA_IMAGE_REPOSITORY), marcada com o SHA do commit do componente. A análise é executada no estágio test em merge requests, na branch padrão, em agendamentos e tags; osa_report_aggregate é o único job que pode bloquear. O dashboard é vinculado como OSS security dashboard no widget de pipeline do MR, e a aba Reports do MR mostra os achados (Security scan, Code Quality).

• Imagens vêm de seus registros públicos (Docker Hub, ghcr.io), em versões fixadas. Atrás de um espelho de registro, substitua as entradas OSA_<TOOL>_IMAGE — consulte Container images.
• Configurações: os padrões da organização se aplicam imediatamente. Para personalizar, adicione qualquer um de security/policy-global.yml, policy-licenses.yml, policy-semgrep.yml, policy-gitleaks.toml, contendo apenas suas diferenças — consulte Customizing oss-analyzer.
• Entradas comuns:

      inputs:
        OSA_DISTRIBUTION_MODEL: distributed   # saas | distributed | oss_library
        OSA_MODE: audit                       # onboarding: report everything, never block
        OSA_JOB_NEEDS: ["build"]              # wait for your build first
  

  Cada entrada está documentada na página do CI/CD Catalog do componente e em templates/analyze.yml.
• Projeto com um backlog: OSA_MODE: audit reporta tudo e não bloqueia nada. OSA_GATE_SCOPE: new mantém o bloqueio apenas do que é novo: num merge request, apenas o que ainda não está no relatório bem-sucedido mais recente da branch de destino bloqueia; nos restantes casos, os achados são reportados sem bloqueio (pelo que requer pipelines de merge request). Ver Apenas novos achados.
• Comentário de resumo no MR: OSA_ENABLE_MR_COMMENT: true publica o veredicto, os achados bloqueantes e o link do dashboard como um único comentário, atualizado por cada pipeline. Requer um token de acesso ao projeto (scope api, role Reporter) numa variável CI/CD mascarada OSA_GITLAB_TOKEN.
• Projeto Maven: o Maven Central limita os runners partilhados, e o grafo de dependências resolvido é então perdido. OSA_MAVEN_MIRROR_URL (por exemplo, um remoto Maven Central do seu repositório de artefactos), com uma variável mascarada OSA_MAVEN_MIRROR_AUTH se precisar de credenciais, resolve através de um mirror em vez disso — ver Armadilhas conhecidas.
• Versões: fixe uma versão minor (@0.4 segue os seus patches). A interface 0.x pode ainda mudar até à 1.0.0: uma alteração disruptiva incrementa a versão minor, ver CHANGELOG.md.

Workflow reutilizável do GitHub Actions

jobs:
  security:
    uses: ThalesGroup/oss-analyzer/.github/workflows/security.yml@<ref>
    with:
      oss-analyzer-repository: ThalesGroup/oss-analyzer
      oss-analyzer-ref: <ref>   # the same ref as in `uses:`

Entradas, permissões e segredos: consulte GitHub Actions.

Análise local, sem CI

Analise um arquivo de projeto recebido (.zip, .tar.gz) ou pasta sem configurar CI:

security/scripts/analyze-archive.sh my-project.zip

O relatório e um dashboard HTML ficam em security-reports/<project-name>/ — consulte Usage.

Documentação

A documentação completa está em security/README.md: configuração, todas as entradas e definições, os relatórios, armadilhas conhecidas. CHANGELOG.md lista as versões, com as mudanças incompatíveis primeiro.

Por que oss-analyzer

Existem bons scanners de código aberto para cada preocupação: Semgrep, Gitleaks, Syft, Grype, OSV-Scanner, Trivy, cdxgen, REUSE. O que falta a uma equipe raramente é mais um scanner. É a parte entre eles: uma decisão em vez de uma pilha de relatórios, regras que são escritas em vez de memorizadas, e licenças tratadas com a mesma seriedade que CVEs. oss-analyzer é essa parte.

Uma análise, todo o software

Cada execução examina as três superfícies do que você entrega, em conjunto: