-
Notifications
You must be signed in to change notification settings - Fork 0
Documentação do Jenkins Server Config
Repositório analisado: jenkins-server-config
URL: https://github.com/Pipeline-DevSecOps-para-Blockchain-2025/jenkins-server-config
Cópia local: Rlatorio/jenkins-server-config
Objetivo: documentar a infraestrutura do servidor Jenkins usada como ambiente de produção para a pipeline DevSecOps de smart contracts Solidity.
Este documento descreve o repositório jenkins-server-config, responsável por provisionar e configurar um servidor Jenkins voltado à execução das pipelines do projeto Pipeline DevSecOps para Segurança de Aplicações Blockchain.
Enquanto o repositório poc-sast-dast-sca concentra os contratos de teste, Dockerfiles das ferramentas, scripts e Jenkinsfile da pipeline, o repositório jenkins-server-config concentra a infraestrutura do servidor Jenkins: sistema operacional, usuários, serviços, proxy reverso, TLS, Jenkins Configuration as Code, plugins, integração com GitHub, execução de containers e observabilidade.
O objetivo é permitir que outro leitor consiga compreender:
- Qual problema esse repositório resolve.
- Como o servidor Jenkins é provisionado.
- Quais componentes compõem o ambiente.
- Como Jenkins, Docker/Podman, Nginx, Grafana e VictoriaMetrics se integram.
- Como reproduzir o deploy do ambiente.
- Quais evidências devem ser coletadas para o relatório final.
O jenkins-server-config usa Ansible para configurar um host Fedora. A infraestrutura é organizada em dois grupos principais de serviços:
| Grupo | Descrição |
|---|---|
| system | Configura pacotes base, atualização do sistema, firewall, usuário não privilegiado, Nginx, SSH, Certbot, ferramentas interativas e Podman. |
| user | Configura serviços rootless executados pelo usuário runner, incluindo Jenkins, Docker-in-Docker, Grafana, renderer e VictoriaMetrics. |
O playbook principal é:
playbooks/devsecops-server.yaml
Esse playbook aplica os seguintes papéis:
roles:
- dnf
- firewalld
- unprivileged_user
- nginx
- sshd
- certbot
- interactive_tools
- podman
- jenkins
- grafanaflowchart TD
User["Usuário / Desenvolvedor"] -->|HTTPS| Nginx["Nginx Reverse Proxy"]
GitHub["GitHub Organization"] -->|Webhooks| Nginx
Nginx --> Jenkins["Jenkins Controller"]
Nginx --> Grafana["Grafana"]
Jenkins -->|Docker API TCP| DinD["Docker-in-Docker daemon"]
Jenkins -->|SCM / GitHub App| GitHub
Jenkins -->|Executa pipelines| Agents["Docker Agents"]
Agents --> Tools["Imagens de ferramentas SAST/DAST/SCA"]
Jenkins --> Metrics["/prometheus metrics"]
Victoria["VictoriaMetrics"] -->|scrape| Metrics
Grafana -->|datasource| Victoria
| Componente | Função |
|---|---|
| Ansible | Automatiza o provisionamento e a configuração do servidor. |
| Fedora | Sistema operacional alvo do host. |
| Podman | Executa os serviços em containers usando quadlets/systemd. |
| Jenkins | Orquestra pipelines CI/CD e executa a análise DevSecOps. |
| Docker-in-Docker | Fornece daemon Docker para agentes e pipelines que precisam executar containers. |
| Nginx | Atua como proxy reverso para Jenkins e Grafana. |
| Certbot | Emite e renova certificados TLS quando configure_tls está habilitado. |
| Grafana | Visualiza métricas do Jenkins e métricas de segurança da pipeline. |
| VictoriaMetrics | Armazena métricas coletadas do Jenkins. |
| firewalld | Controla exposição de portas HTTP, HTTPS e SSH. |
| sshd | Permite administração remota com configuração endurecida. |
jenkins-server-config/
├── ansible.cfg
├── hosts
├── cloud-init/
├── group_vars/
├── host_vars/
├── playbooks/
│ └── devsecops-server.yaml
├── roles/
│ ├── certbot/
│ ├── dnf/
│ ├── firewalld/
│ ├── grafana/
│ ├── interactive_tools/
│ ├── jenkins/
│ ├── nginx/
│ ├── podman/
│ ├── sshd/
│ └── unprivileged_user/
└── secret_vars/
| Arquivo | Finalidade |
|---|---|
ansible.cfg |
Define inventário, usuário remoto, roles path, tags padrão e opções SSH. |
hosts |
Inventário Ansible com hosts Fedora. |
playbooks/devsecops-server.yaml |
Playbook principal de provisionamento. |
group_vars/all/common.yaml |
Variáveis comuns, como domínio padrão, aliases e parâmetros gerais. |
host_vars/jenkins-server-docker/misc.yaml |
Variáveis específicas do host Jenkins. |
secret_vars/*.yaml |
Segredos carregados via Ansible Vault. Não devem ser expostos em texto claro. |
cloud-init/cloud-config.yaml |
Bootstrap inicial do host com Ansible pull. |
O fluxo de deploy é conduzido por Ansible. O comando principal documentado no repositório é:
ansible-playbook playbooks/devsecops-server.yaml -l jenkins-server-docker --ask-vault-passPara atualizar serviços que exigem privilégios de root:
ansible-playbook playbooks/devsecops-server.yaml -l jenkins-server-docker --tags all --ask-vault-pass -Kb| Tag | Uso |
|---|---|
system |
Aplica configuração do sistema, pacotes, firewall, Nginx, SSH, Podman e usuário. |
user |
Aplica serviços rootless do usuário runner. |
jenkins |
Aplica apenas a configuração do Jenkins. |
grafana |
Aplica apenas a configuração de observabilidade. |
bootstrap |
Usada no fluxo de bootstrap com cloud-init/Ansible pull. |
O papel unprivileged_user cria o usuário runner, configura chaves SSH autorizadas e habilita linger para permitir serviços systemd de usuário mesmo sem sessão interativa ativa.
Esse desenho reduz a necessidade de executar os serviços principais como root. Jenkins, Docker-in-Docker, Grafana e VictoriaMetrics são configurados como containers rootless por meio de quadlets em:
/home/runner/.config/containers/systemd
O repositório também cria uma rede compartilhada de serviços via quadlet:
[Network]
Label=service=allEssa rede permite comunicação entre Jenkins, Docker-in-Docker, Grafana e VictoriaMetrics.
O Jenkins é construído a partir da imagem oficial:
FROM docker.io/jenkins/jenkins:alpineO Containerfile instala plugins a partir de:
roles/jenkins/files/build/plugins.txt
Também define opções de Java e marca o estado do wizard de instalação como concluído:
RUN jenkins-plugin-cli --plugin-file ${REF}/plugins.txt --clean-download-directory \
&& echo 2.0 > ${REF}/jenkins.install.UpgradeWizard.stateIsso permite que o Jenkins suba já configurado por código, sem depender de configuração manual inicial.
Os plugins incluem:
| Grupo | Plugins principais |
|---|---|
| Pipeline |
workflow-aggregator, pipeline-graph-view, pipeline-utility-steps
|
| Docker |
docker-plugin, docker-workflow
|
| GitHub |
github-branch-source, github-checks, github-scm-trait-notification-context
|
| Segurança/autorização |
matrix-auth, antisamy-markup-formatter, audit-trail
|
| Observabilidade |
metrics, prometheus, cloudbees-disk-usage-simple
|
| Notificações | email-ext |
| Qualidade de execução |
build-timeout, timestamper, ws-cleanup, warnings-ng
|
| Interface |
dark-theme, theme-manager
|
| Configuração como código |
configuration-as-code, job-dsl
|
A configuração principal do Jenkins é gerada por:
roles/jenkins/templates/jenkins.yaml.j2
Essa configuração define:
- Estratégia de autorização com matriz global.
- Usuários locais com senha bcrypt.
- Integração com Docker cloud.
- Porta de agentes.
- Tema e aparência.
- Configurações de segurança.
- Credenciais do GitHub App, PAT, webhook secret e SendGrid.
- Jobs gerados via Job DSL.
- Configuração de e-mail.
- Auditoria e métricas.
O Jenkins usa matriz global:
authorizationStrategy:
globalMatrix:
entries:
- user:
name: anonymous
permissions:
- Job/Read
- Metrics/View
- Overall/Read
- View/Read
- group:
name: authenticated
permissions:
- Overall/AdministerUsuários autenticados recebem administração. Usuário anônimo recebe apenas permissões de leitura/visualização e métricas.
O Jenkins é integrado ao GitHub por meio de:
- GitHub App.
- GitHub Personal Access Token.
- Webhook secret.
- GitHub Checks.
- Organization Folder via Job DSL.
O job principal é criado a partir de:
roles/jenkins/files/jobs/Pipeline-DevSecOps-para-Blockchain-2025.jenkins
Ele configura uma organização GitHub:
organizationFolder('Pipeline-DevSecOps-para-Blockchain-2025') {
organizations {
github {
repoOwner('Pipeline-DevSecOps-para-Blockchain-2025')
credentialsId('Pipeline-DevSecOps-Jenkins')
}
}
}Esse padrão permite que o Jenkins descubra repositórios e Pull Requests da organização, publique status checks e execute pipelines versionadas nos repositórios.
O Jenkins usa um Docker cloud chamado local-docker, conectado ao daemon:
dockerHost:
uri: tcp://dockerd:2375O serviço dockerd é definido como container Podman com imagem:
docker.io/docker:dind
O quadlet dockerd.container usa:
PodmanArgs=--privileged
Environment=DOCKER_TLS_CERTDIR=Isso permite que o Jenkins execute agentes Docker e pipelines que precisam chamar Docker. No contexto do projeto, essa capacidade é importante porque as ferramentas SAST, DAST e SCA são executadas em containers.
No Jenkins, o controller é responsável por gerenciar a configuração, autenticação, plugins, jobs, filas de execução e histórico de builds. Já os agents são os ambientes onde os comandos da pipeline são executados de fato [1]. Essa separação é importante porque evita concentrar todo o trabalho pesado no controller e permite criar ambientes diferentes para tipos diferentes de execução.
No contexto deste projeto, os agents são especialmente relevantes porque cada etapa da pipeline de segurança precisa de dependências específicas. Uma análise SAST pode exigir Slither, compiladores solc e bibliotecas Python; uma etapa DAST pode exigir Foundry, Anvil, Echidna ou ferramentas de fuzzing; e uma etapa SCA pode exigir ferramentas de inspeção de dependências. Em vez de instalar tudo diretamente no servidor Jenkins, o projeto usa containers para encapsular essas dependências.
O fluxo conceitual é:
- O Jenkins controller recebe um evento do GitHub ou uma execução manual.
- O controller coloca o job na fila e avalia o
Jenkinsfile. - O Docker plugin solicita ao Docker daemon a criação de um agent container [2].
- O agent é iniciado com a imagem configurada no Jenkins CasC.
- A pipeline executa comandos dentro desse ambiente isolado.
- As ferramentas SAST, DAST e SCA rodam em containers ou imagens específicas.
- O Jenkins coleta logs, relatórios, status de build e métricas.
- Ao final da execução, o agent pode ser descartado.
Esse modelo se aproxima de uma execução efêmera: o ambiente de build nasce para uma execução, realiza o trabalho e depois é removido. Isso melhora a reprodutibilidade, reduz acúmulo de estado entre builds e facilita a comparação entre execuções, porque a pipeline passa a depender mais de imagens versionadas do que de instalações manuais no host.
No repositório jenkins-server-config, os agents são definidos dentro da configuração Jenkins CasC em:
roles/jenkins/templates/jenkins.yaml.j2
A configuração cria um Docker cloud chamado local-docker, que aponta para o daemon Docker-in-Docker:
clouds:
- docker:
name: local-docker
dockerApi:
dockerHost:
uri: tcp://dockerd:2375Na prática, isso significa que o Jenkins controller não executa diretamente os comandos de análise. Ele conversa com o serviço dockerd, que cria containers de agent sob demanda. Esses agents recebem o workspace do job, executam os comandos declarados na pipeline e retornam os resultados para o controller.
O Docker plugin permite esse provisionamento dinâmico de agents: o administrador define templates de containers, labels e limites de capacidade; quando um job precisa de um agent compatível, o Jenkins cria o container, executa o build e remove o ambiente depois [2]. Esse comportamento é adequado para o projeto porque as análises de segurança podem ser pesadas, variáveis e dependentes de versões específicas de ferramentas.
Além disso, o plugin docker-workflow permite que o Jenkinsfile utilize Docker diretamente dentro da pipeline. Isso é útil quando uma etapa precisa executar uma imagem específica, construir uma imagem temporária, reaproveitar workspace ou isolar ferramentas por estágio [3]. Para o leitor que deseja reproduzir o projeto, essa diferença é importante:
| Elemento | Responsabilidade no projeto |
|---|---|
| Jenkins controller | Orquestra jobs, plugins, credenciais, histórico e integração com GitHub. |
Docker cloud local-docker
|
Define o provedor de agents Docker usado pelo Jenkins. |
Docker-in-Docker dockerd
|
Fornece a API Docker usada para criar agents e containers de execução. |
| Agent container | Ambiente temporário onde a pipeline roda comandos. |
| Imagens das ferramentas | Ambientes específicos para Slither, Foundry, Mythril, SmartBugs ou outras ferramentas. |
| Workspace | Código do repositório analisado, montado ou copiado para a execução. |
Esse desenho também ajuda a explicar por que o projeto investiu na criação e comparação de imagens Docker próprias. Ao padronizar as imagens usadas pelos agents e pelas etapas de análise, a pipeline fica mais previsível: a mesma versão de ferramenta, compilador e dependências pode ser usada localmente, no GitHub Actions e no Jenkins.
Agents Jenkins podem usar labels para indicar capacidades específicas, como docker, sast, dast, foundry ou slither [1]. Mesmo que a configuração atual use um Docker cloud genérico, uma evolução natural do ambiente é separar templates por categoria de ferramenta:
| Label sugerida | Uso esperado |
|---|---|
sast |
Execução de Slither, Mythril, Aderyn ou SmartBugs. |
dast |
Execução de Foundry, Anvil, Medusa, Halmos ou Echidna. |
sca |
Inspeção de dependências, lockfiles, pacotes e imagens. |
docker-build |
Construção e publicação de imagens Docker do projeto. |
reporting |
Consolidação de relatórios, métricas e artefatos. |
Separar agents por labels ajuda a controlar onde cada job roda, evita misturar workloads incompatíveis e facilita limitar recursos por tipo de análise. Em uma pipeline de segurança para smart contracts, isso tem valor prático porque fuzzing e execução dinâmica tendem a consumir mais CPU e tempo do que verificações estáticas simples.
Também é recomendável limitar a quantidade de containers simultâneos por template. O Docker plugin possui configuração de capacidade para evitar que muitos builds concorrentes consumam todo o host [2]. Para o projeto, esse limite deve ser ajustado conforme CPU, memória, tamanho dos contratos e duração média das análises.
O uso de agents containerizados melhora a organização operacional, mas não elimina riscos. Como a configuração usa Docker-in-Docker privilegiado, qualquer pipeline com permissão para executar comandos Docker deve ser tratada como sensível. Em termos práticos, pipelines vindas de branches ou Pull Requests não confiáveis não devem receber o mesmo nível de acesso que pipelines internas controladas.
Os principais cuidados são:
- Restringir quem pode alterar
Jenkinsfilee scripts executados no Jenkins. - Evitar expor tokens e chaves privadas para builds de origem não confiável.
- Revisar permissões do GitHub App e do PAT usados pelo Jenkins.
- Manter imagens de agents atualizadas e versionadas.
- Limitar capacidade concorrente para reduzir risco de exaustão de recursos.
- Separar labels/templates para workloads de maior risco.
- Coletar logs e métricas para investigar execuções anômalas.
- Avaliar alternativas futuras ao DinD privilegiado, como agentes Kubernetes, Docker remoto com TLS ou Podman com políticas mais restritas.
Portanto, os agents são uma peça central da arquitetura: eles tornam a pipeline reproduzível e escalável, mas também são um ponto crítico de segurança. A documentação final deve deixar claro que o Jenkins controller orquestra, enquanto os agents executam o trabalho técnico da pipeline.
O Nginx atua como proxy reverso para Jenkins e Grafana.
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_buffering off;
}location /grafana/ {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}Quando configure_tls está habilitado, o papel certbot solicita certificado via webroot e reconfigura o Nginx para HTTPS. Também instala hook para recarregar Nginx após renovação de certificado.
O firewall libera:
- HTTP.
- HTTPS.
- SSH.
O repositório possui várias decisões voltadas a um ambiente mais seguro:
| Controle | Implementação |
|---|---|
| Usuário não privilegiado | Serviços executados pelo usuário runner. |
| Podman rootless | Serviços de usuário via quadlets. |
| Segredos | Uso de Ansible Vault e Podman secrets. |
| TLS | Certbot + Nginx quando configure_tls está habilitado. |
| Firewall |
firewalld com liberação explícita de HTTP/HTTPS/SSH. |
| SSH hardening | Arquivos de configuração para autenticação e algoritmos. |
| Jenkins CasC | Configuração versionada e reprodutível. |
| Auditoria Jenkins | Plugin audit-trail com registro de ações sensíveis. |
| Atualizações |
dnf-automatic habilitado para download/aplicação automática. |
Os segredos são carregados a partir de:
secret_vars/{{ inventory_hostname }}.yaml
O README orienta uso de Ansible Vault:
ansible-vault view secret_vars/jenkins-server-docker.yaml
ansible-vault edit secret_vars/jenkins-server-docker.yaml
ansible-vault create secret_vars/novo-host.yaml
ansible-vault encrypt secret_vars/devsecops-libvirt-server.yamlImportante: valores reais de segredos, tokens, chaves privadas, hashes de senha e chaves SSH não devem ser reproduzidos no relatório final. O relatório deve documentar os nomes, finalidade e fluxo de uso dos segredos, mas não seus valores.
O papel grafana configura:
- Grafana.
- Grafana Renderer.
- VictoriaMetrics.
- Datasource do VictoriaMetrics.
- Dashboards provisionados.
- Contact points e políticas de alerta.
O VictoriaMetrics coleta métricas do Jenkins via:
scrape_configs:
- job_name: jenkins
metrics_path: /prometheus/
static_configs:
- targets:
- jenkins:8080O Grafana usa VictoriaMetrics como datasource padrão:
datasources:
- name: VictoriaMetrics
type: victoriametrics-metrics-datasource
url: http://victoriametrics:8428
isDefault: trueAlém dos dashboards de infraestrutura, há um dashboard específico:
roles/grafana/files/dashboards/ci-security-metrics.json
Esse dashboard é importante para o projeto porque permite acompanhar métricas de CI e segurança geradas pela pipeline, como achados por ferramenta, severidade e evolução temporal.
O diretório cloud-init/ permite testar o provisionamento em VM ou VPS. O arquivo cloud-config.yaml instala Git e Ansible e executa ansible-pull apontando para o repositório:
ansible:
install_method: distro
package_name: ansible
pull:
- url: 'https://github.com/Pipeline-DevSecOps-para-Blockchain-2025/jenkins-server-config.git'
playbook_names: [playbooks/devsecops-server.yaml]
connection: local
tags: bootstrap,system
skip_tags: userEsse fluxo permite inicializar uma máquina com configuração básica e depois aplicar o playbook completo.
O repositório também documenta testes com QEMU/libvirt, incluindo geração de imagem seed via cloud-localds e execução de VM Fedora.
O operador precisa de:
- Host Fedora ou VM Fedora.
- Acesso SSH ao host.
- Ansible instalado na máquina de controle ou no próprio host.
- Acesso ao repositório
jenkins-server-config. - Arquivo de segredos disponível via Ansible Vault.
- DNS configurado se TLS público for usado.
- Portas 80, 443 e 22 acessíveis conforme política do ambiente.
Editar o arquivo de segredos do host:
ansible-vault edit secret_vars/jenkins-server-docker.yamlOs segredos esperados incluem, entre outros:
| Segredo | Uso |
|---|---|
github_shared_secret |
Validação de webhooks GitHub. |
github_client_secret |
Integração OAuth/GitHub, quando aplicável. |
github_pat |
Acesso GitHub por token pessoal. |
github_app_private_key |
Autenticação do GitHub App. |
sendgrid_api_key |
Envio de e-mails/notificações. |
grafana_admin_password |
Senha administrativa do Grafana. |
Deploy padrão:
ansible-playbook playbooks/devsecops-server.yaml -l jenkins-server-docker --ask-vault-passDeploy com privilégios para roles de sistema:
ansible-playbook playbooks/devsecops-server.yaml -l jenkins-server-docker --tags all --ask-vault-pass -KbExecutar apenas Jenkins:
ansible-playbook playbooks/devsecops-server.yaml -l jenkins-server-docker --tags jenkins --ask-vault-passExecutar apenas Grafana:
ansible-playbook playbooks/devsecops-server.yaml -l jenkins-server-docker --tags grafana --ask-vault-passNo host:
systemctl status nginx
systemctl status firewalld
loginctl show-user runnerComo usuário runner:
systemctl --user status jenkins
systemctl --user status dockerd
systemctl --user status grafana
systemctl --user status victoriametricsVerificar containers:
podman ps
podman volume ls
podman secret lsValidar endpoints:
curl -I http://localhost:8080
curl -I http://localhost:3000/grafana/
curl -I https://devsecops-blockchain.devO servidor Jenkins configurado por este repositório é o ambiente de execução para pipelines como a do repositório poc-sast-dast-sca.
Fluxo esperado:
- GitHub recebe push ou Pull Request.
- GitHub aciona webhook do Jenkins.
- Jenkins descobre o repositório pela Organization Folder.
- Jenkins executa o
Jenkinsfiledo repositório. - Pipeline usa agentes Docker e imagens das ferramentas.
- Ferramentas geram relatórios.
- Jenkins publica checks e métricas.
- VictoriaMetrics coleta métricas.
- Grafana exibe dashboards de CI e segurança.
[1] Jenkins. Using Jenkins agents. Disponível em: https://www.jenkins.io/doc/book/using/using-agents/. Acesso em: 20 abr. 2026.
[2] Jenkins Plugins. Docker plugin. Disponível em: https://plugins.jenkins.io/docker-plugin/. Acesso em: 20 abr. 2026.
[3] Jenkins. Using Docker with Pipeline. Disponível em: https://www.jenkins.io/doc/book/pipeline/docker/. Acesso em: 20 abr. 2026.
[4] Jenkins Plugins. Configuration as Code plugin. Disponível em: https://plugins.jenkins.io/configuration-as-code/. Acesso em: 20 abr. 2026.
[5] Podman. podman-quadlet. Disponível em: https://docs.podman.io/en/latest/markdown/podman-quadlet.1.html. Acesso em: 20 abr. 2026.
[6] Docker. Docker Engine installation overview. Disponível em: https://docs.docker.com/engine/install/. Acesso em: 20 abr. 2026.
[7] Jenkins. Installing Jenkins with Docker. Disponível em: https://www.jenkins.io/doc/book/installing/docker/. Acesso em: 20 abr. 2026.
[8] Ansible. Ansible Vault. Disponível em: https://docs.ansible.com/ansible/latest/vault_guide/index.html. Acesso em: 20 abr. 2026.
O repositório jenkins-server-config representa a camada de infraestrutura de produção do projeto. Ele transforma o Jenkins de uma ferramenta isolada em um ambiente operacional completo, com provisionamento automatizado, configuração como código, integração com GitHub, execução de containers, proxy reverso, TLS, observabilidade e controles básicos de segurança.
Essa infraestrutura é essencial para que a pipeline DevSecOps proposta seja executada de forma contínua, reproduzível e auditável. A combinação entre Ansible, Podman quadlets, Jenkins CasC, Docker-in-Docker, Nginx, Certbot, Grafana e VictoriaMetrics fornece a base necessária para executar as ferramentas de análise de smart contracts e coletar evidências técnicas para o relatório geral.
- Home
- Relatórios
- Pipeline e Infraestrutura
- Análise de Ferramentas
- Gerenciamento do projeto
- Resultados obtidos
- Contribuição