Skip to content

Commit 51e9139

Browse files
r2WillDevr2WillDev
committed
docs: document C1 baseline pipeline
1 parent 8cfe0f2 commit 51e9139

1 file changed

Lines changed: 363 additions & 0 deletions

File tree

‎docs/05-c1-baseline-pipeline.md‎

Lines changed: 363 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,363 @@
1+
# Etapa 5 — C1: Pipeline Baseline
2+
3+
> **Repositório:** [r2WillDev/tcc-devsecops-pipeline](https://github.com/r2WillDev/tcc-devsecops-pipeline)
4+
> **Branch:** `feature/c1-baseline-pipeline`
5+
> **Commits relacionados:** `0ef27c7`, `8cfe0f2`
6+
7+
---
8+
9+
## 🧭 Sumário
10+
11+
1. [Objetivo da Etapa](#1-objetivo-da-etapa)
12+
2. [Relação com o Problema de Pesquisa](#2-relação-com-o-problema-de-pesquisa)
13+
3. [Conceito de Pipeline Baseline](#3-conceito-de-pipeline-baseline)
14+
4. [Escopo do C1](#4-escopo-do-c1)
15+
5. [Decisão Técnica](#5-decisão-técnica)
16+
6. [Arquivos Criados](#6-arquivos-criados)
17+
7. [Funcionamento do Workflow](#7-funcionamento-do-workflow)
18+
8. [Métricas Coletadas](#8-métricas-coletadas)
19+
9. [Validações Manuais Realizadas](#9-validações-manuais-realizadas)
20+
10. [Resultado Inicial do Workflow](#10-resultado-inicial-do-workflow)
21+
11. [Próximos Passos](#11-próximos-passos)
22+
12. [Observações Acadêmicas](#12-observações-acadêmicas)
23+
13. [Resumo da Etapa](#13-resumo-da-etapa)
24+
25+
---
26+
27+
## 1. 🎯 Objetivo da Etapa
28+
29+
Esta etapa tem como objetivo a implementação do **Cenário C1 — Pipeline Baseline**, que representa a configuração mínima e funcional de um pipeline CI/CD sem a integração de qualquer ferramenta de análise de segurança.
30+
31+
O C1 cumpre o papel de **cenário de referência experimental** do trabalho de conclusão de curso. Todas as medições coletadas neste cenário serão utilizadas como base comparativa para os cenários subsequentes, que incorporarão progressivamente ferramentas de segurança ao pipeline.
32+
33+
Os objetivos específicos desta etapa são:
34+
35+
- Criar o arquivo de workflow do GitHub Actions para o C1;
36+
- Implementar um script de medição de tempo para as etapas do pipeline;
37+
- Gerar automaticamente um arquivo CSV com as métricas coletadas por execução;
38+
- Validar manualmente o fluxo completo antes de automatizá-lo;
39+
- Garantir a reprodutibilidade das execuções em ambiente controlado.
40+
41+
---
42+
43+
## 2. Relação com o Problema de Pesquisa
44+
45+
O problema de pesquisa deste TCC é:
46+
47+
> *Como a integração de ferramentas de análise de segurança — SAST, DAST e SCA — afeta o lead time em pipelines CI/CD, e como otimizar esse impacto?*
48+
49+
Para responder a essa pergunta de forma rigorosa, é necessário estabelecer uma **linha de base mensurável**. O C1 cumpre exatamente essa função: ao executar o pipeline sem nenhuma ferramenta de segurança, é possível determinar o tempo de execução natural do fluxo de entrega contínua.
50+
51+
A partir dos dados coletados no C1, será possível calcular, nos cenários seguintes, o **delta de tempo** introduzido por cada ferramenta de segurança, isolando o impacto de cada prática DevSecOps no lead time do pipeline.
52+
53+
---
54+
55+
## 3. Conceito de Pipeline Baseline
56+
57+
No contexto de experimentos controlados em engenharia de software, um **pipeline baseline** é aquele que executa apenas as etapas fundamentais de um fluxo CI/CD, sem acréscimos de ferramentas adicionais. Ele representa o estado mais simples e funcional do pipeline.
58+
59+
No contexto deste TCC, o C1 — Pipeline Baseline contempla:
60+
61+
| Incluído no C1 | Excluído do C1 |
62+
|---|---|
63+
| Checkout do código | SonarQube (SAST) |
64+
| Instalação de dependências | Trivy (SCA) |
65+
| Execução de testes unitários | OWASP ZAP (DAST) |
66+
| Build da imagem Docker | Qualquer outra análise de segurança |
67+
| Deploy no Kubernetes (kind) | |
68+
| Smoke test no endpoint `/health` | |
69+
| Coleta de métricas de tempo | |
70+
71+
Essa delimitação garante que o tempo medido no C1 reflita exclusivamente o custo do processo de entrega, sem interferência das práticas de segurança que serão avaliadas nos cenários seguintes.
72+
73+
---
74+
75+
## 4. Escopo do C1
76+
77+
O cenário C1 faz parte de uma série de cinco cenários experimentais planejados para o TCC:
78+
79+
| Cenário | Descrição |
80+
|---|---|
81+
| **C1** | Pipeline Baseline (sem segurança) — *esta etapa* |
82+
| C2 | Baseline + SAST (SonarQube) |
83+
| C3 | Baseline + SAST + SCA (Trivy) |
84+
| C4 | Baseline + SAST + SCA + DAST (OWASP ZAP) |
85+
| C5 | Pipeline Otimizado |
86+
87+
O C1 é o ponto de partida do experimento. Sem ele, não é possível quantificar o impacto de nenhuma das ferramentas de segurança nos cenários posteriores. Por isso, sua implementação e validação são etapas críticas para a integridade metodológica da pesquisa.
88+
89+
---
90+
91+
## 5. Decisão Técnica
92+
93+
### 5.1 Ambiente de Execução
94+
95+
O workflow C1 foi implementado utilizando **GitHub-hosted runner**, conforme configuração:
96+
97+
```yaml
98+
runs-on: ubuntu-latest
99+
```
100+
101+
Essa decisão foi tomada após análise das alternativas disponíveis. A tabela a seguir compara as duas abordagens principais:
102+
103+
| Critério | GitHub-hosted Runner | Self-hosted Runner |
104+
|---|---|---|
105+
| Reprodutibilidade | Alta — ambiente padronizado pelo GitHub | Média — depende da máquina local |
106+
| Independência da máquina local | Sim | Não |
107+
| Facilidade de repetição | Alta | Baixa (requer máquina disponível) |
108+
| Complexidade de configuração inicial | Baixa | Alta |
109+
| Adequação ao experimento | Recomendada | Não adotada nesta fase |
110+
111+
A escolha pelo GitHub-hosted runner garante que cada execução do workflow ocorra em um **ambiente isolado e equivalente**, condição essencial para a validade dos dados experimentais coletados.
112+
113+
### 5.2 Cluster Kubernetes Efêmero
114+
115+
O cluster Kubernetes utilizado neste workflow é criado com **kind** (*Kubernetes in Docker*) diretamente no runner do GitHub Actions, durante a execução do pipeline. Esse cluster possui natureza **efêmera**: é criado no início da execução e descartado automaticamente ao término, sem persistência entre execuções.
116+
117+
Essa abordagem foi adotada pelos seguintes motivos:
118+
119+
- Elimina a necessidade de um cluster externo permanente;
120+
- Garante que cada execução parta de um estado limpo e previsível;
121+
- Simplifica a configuração do ambiente experimental;
122+
- Evita interferências entre execuções consecutivas.
123+
124+
A criação do cluster é automatizada dentro do próprio workflow, sem intervenção manual.
125+
126+
---
127+
128+
## 6. Arquivos Criados
129+
130+
Nesta etapa, foram criados os seguintes arquivos no repositório:
131+
132+
### 6.1 `.github/workflows/c1-baseline.yml`
133+
134+
Define o workflow do GitHub Actions para o cenário C1. Contém todas as etapas do pipeline, desde o checkout do código até o upload do CSV de métricas como artifact.
135+
136+
```
137+
.github/
138+
└── workflows/
139+
└── c1-baseline.yml
140+
```
141+
142+
### 6.2 `ci/scripts/measure_step.sh`
143+
144+
Script Bash responsável por medir o tempo de execução das etapas principais do pipeline. O script registra o instante de início, executa a etapa correspondente e registra o instante de término, calculando a duração em segundos. O resultado é escrito no arquivo CSV de métricas.
145+
146+
```
147+
ci/
148+
└── scripts/
149+
└── measure_step.sh
150+
```
151+
152+
### 6.3 `analysis/raw/c1_baseline.csv`
153+
154+
Arquivo-base que define o cabeçalho do CSV de resultados do cenário C1. Cada execução do workflow gera uma nova linha neste arquivo, que é então enviado como artifact ao GitHub Actions.
155+
156+
```
157+
analysis/
158+
└── raw/
159+
└── c1_baseline.csv
160+
```
161+
162+
### 6.4 `.gitattributes`
163+
164+
Define a configuração de final de linha para os arquivos do repositório, forçando o uso de `LF` para arquivos `.sh`, `.yml` e `.yaml`. Essa configuração evita problemas de execução no ambiente Linux do GitHub Actions, que podem ocorrer quando arquivos são editados em sistemas Windows (que utilizam `CRLF` por padrão).
165+
166+
```
167+
# .gitattributes
168+
*.sh text eol=lf
169+
*.yml text eol=lf
170+
*.yaml text eol=lf
171+
```
172+
173+
---
174+
175+
## 7. Funcionamento do Workflow
176+
177+
O workflow `c1-baseline.yml` executa as seguintes etapas, na ordem indicada:
178+
179+
| # | Etapa | Descrição |
180+
|---|---|---|
181+
| 1 | **Checkout do código** | Clona o repositório na branch em execução |
182+
| 2 | **Preparação do CSV** | Cria o arquivo CSV com o cabeçalho das métricas |
183+
| 3 | **Configuração do Python 3.12** | Instala e configura o interpretador Python |
184+
| 4 | **Permissão do script** | Concede permissão de execução ao `measure_step.sh` |
185+
| 5 | **Instalação de dependências** | Instala as dependências Python via `pip` (medida) |
186+
| 6 | **Testes unitários** | Executa os testes com Pytest (medida) |
187+
| 7 | **Build da imagem Docker** | Constrói a imagem da aplicação (medida) |
188+
| 8 | **Instalação do kind** | Baixa e instala o kind no runner |
189+
| 9 | **Criação do cluster** | Inicializa o cluster Kubernetes local no runner |
190+
| 10 | **Deploy no Kubernetes** | Aplica os manifests e aguarda o pod ficar disponível (medida) |
191+
| 11 | **Smoke test** | Verifica a resposta do endpoint `/health` (medida) |
192+
| 12 | **Tempo total** | Calcula e registra a duração total do workflow |
193+
| 13 | **Exibição das métricas** | Imprime as métricas coletadas no log do workflow |
194+
| 14 | **Resumo no GitHub Actions** | Escreve um resumo formatado na aba *Summary* do workflow |
195+
| 15 | **Upload do CSV** | Envia o CSV como artifact para download posterior |
196+
197+
As etapas marcadas como **medidas** são aquelas cujo tempo de execução é registrado no CSV de métricas, conforme detalhado na seção seguinte.
198+
199+
---
200+
201+
## 8. Métricas Coletadas
202+
203+
### 8.1 Estrutura do CSV
204+
205+
O arquivo CSV gerado por cada execução segue o seguinte esquema:
206+
207+
```
208+
scenario,run_id,run_number,commit_sha,step_name,start_timestamp,end_timestamp,duration_seconds,status
209+
```
210+
211+
| Campo | Descrição |
212+
|---|---|
213+
| `scenario` | Identificador do cenário (`C1`) |
214+
| `run_id` | ID único da execução no GitHub Actions |
215+
| `run_number` | Número sequencial da execução |
216+
| `commit_sha` | Hash do commit que disparou o workflow |
217+
| `step_name` | Nome da etapa medida |
218+
| `start_timestamp` | Instante de início da etapa (ISO 8601) |
219+
| `end_timestamp` | Instante de término da etapa (ISO 8601) |
220+
| `duration_seconds` | Duração em segundos |
221+
| `status` | Status da etapa (`success` ou `failure`) |
222+
223+
### 8.2 Etapas Medidas
224+
225+
As seguintes etapas têm seu tempo de execução registrado no CSV:
226+
227+
| Etapa (`step_name`) | O que representa |
228+
|---|---|
229+
| `install_dependencies` | Instalação das dependências Python |
230+
| `unit_tests` | Execução dos testes unitários com Pytest |
231+
| `docker_build` | Build da imagem Docker da aplicação |
232+
| `kubernetes_deploy` | Deploy no cluster kind e aguardo do pod |
233+
| `kubernetes_smoke_test` | Verificação do endpoint `/health` |
234+
| `workflow_total` | Duração total do workflow de ponta a ponta |
235+
236+
### 8.3 Resultado de uma Execução Inicial
237+
238+
A tabela a seguir apresenta os valores registrados em uma execução inicial do workflow C1, realizados para validação do pipeline:
239+
240+
| Etapa | Duração |
241+
|---|---:|
242+
| `install_dependencies` | 7s |
243+
| `unit_tests` | 2s |
244+
| `docker_build` | 14s |
245+
| `kubernetes_deploy` | 28s |
246+
| `kubernetes_smoke_test` | 5s |
247+
| `workflow_total` | 83s |
248+
249+
> [!NOTE]
250+
> Os valores acima são provenientes de uma execução inicial de validação e têm caráter ilustrativo. Os dados utilizados na análise estatística do TCC serão coletados nas **cinco execuções oficiais** planejadas para esta etapa. Esses resultados serão documentados posteriormente.
251+
252+
---
253+
254+
## 9. Validações Manuais Realizadas
255+
256+
Antes de automatizar o fluxo no GitHub Actions, todas as etapas do C1 foram validadas manualmente no ambiente local. Essa prática garante que eventuais problemas sejam identificados e corrigidos antes de consumir minutos de execução no runner remoto.
257+
258+
### 9.1 Checklist de Validação Local
259+
260+
| Item Validado | Status |
261+
|---|---|
262+
| Branch `feature/c1-baseline-pipeline` criada | Concluído |
263+
| Arquivos da aplicação FastAPI presentes | Concluído |
264+
| Arquivos Docker (`Dockerfile`, `docker-compose.yml`) presentes | Concluído |
265+
| Manifests Kubernetes presentes | Concluído |
266+
| Testes locais executando e passando | Concluído |
267+
| Docker build local funcionando | Concluído |
268+
| Cluster kind local recriado com sucesso | Concluído |
269+
| `kubectl` acessando o cluster corretamente | Concluído |
270+
| Deploy Kubernetes manual executado com sucesso | Concluído |
271+
| Pod da aplicação em status `Running` | Concluído |
272+
| Endpoint `/` respondendo corretamente | Concluído |
273+
| Endpoint `/health` respondendo corretamente | Concluído |
274+
275+
### 9.2 Respostas dos Endpoints Validadas
276+
277+
**Endpoint raiz (`/`):**
278+
279+
```json
280+
{"message": "TCC DevSecOps API"}
281+
```
282+
283+
**Endpoint de saúde (`/health`):**
284+
285+
```json
286+
{"status": "ok"}
287+
```
288+
289+
A validação manual confirmou que a aplicação, a imagem Docker e os manifests Kubernetes estão funcionando corretamente, habilitando a automação segura do fluxo via GitHub Actions.
290+
291+
---
292+
293+
## 10. Resultado Inicial do Workflow
294+
295+
O workflow `C1 - Baseline Pipeline` foi executado com sucesso no GitHub Actions após a criação e os ajustes iniciais.
296+
297+
### 10.1 Commits Realizados
298+
299+
| Hash | Mensagem |
300+
|---|---|
301+
| `0ef27c7` | `ci: add baseline workflow for C1` |
302+
| `8cfe0f2` | `ci: add total duration metric to C1 workflow` |
303+
304+
O segundo commit (`8cfe0f2`) foi necessário para incluir a métrica `workflow_total`, que registra a duração completa do workflow de ponta a ponta. Essa métrica é fundamental para a análise comparativa entre os cenários.
305+
306+
### 10.2 Status das Execuções Iniciais
307+
308+
A execução inicial confirmou o funcionamento correto do pipeline, com todas as etapas concluídas com sucesso e o CSV de métricas gerado e disponível como artifact.
309+
310+
> As **cinco execuções oficiais** do C1, destinadas à coleta dos dados experimentais do TCC, estão planejadas e serão realizadas na sequência desta validação. Os resultados serão consolidados conforme descrito na seção de próximos passos.
311+
312+
---
313+
314+
## 11. Próximos Passos
315+
316+
Após a validação inicial do workflow C1, as ações imediatas previstas são:
317+
318+
1. **Executar o workflow C1 pelo menos cinco vezes**, de forma independente, para garantir uma amostra representativa dos tempos de execução;
319+
2. **Baixar os artifacts** gerados em cada execução a partir da interface do GitHub Actions;
320+
3. **Salvar os CSVs** individuais de cada execução na estrutura de diretórios definida na seção anterior;
321+
4. **Consolidar os resultados** em um único arquivo CSV para facilitar a análise;
322+
5. **Calcular as estatísticas descritivas** para cada etapa medida: média, mínimo, máximo e coeficiente de variação;
323+
6. **Utilizar os dados consolidados do C1 como base de comparação** para os cenários C2, C3, C4 e C5.
324+
325+
> **Importante:** O avanço para o próximo cenário (C2 — com SonarQube) somente deve ocorrer após a conclusão completa das cinco execuções oficiais do C1 e a consolidação dos dados coletados. Não devem ser iniciadas nesta etapa as implementações de SonarQube, Trivy ou OWASP ZAP.
326+
327+
---
328+
329+
## 12. Observações Acadêmicas
330+
331+
### 12.1 Validade Interna do Experimento
332+
333+
A coleta de múltiplas execuções do mesmo cenário é uma prática estabelecida em experimentos controlados de engenharia de software. O número mínimo de cinco execuções para o C1 visa mitigar variações causadas por fatores externos ao pipeline, como flutuações na disponibilidade de recursos do runner do GitHub Actions.
334+
335+
A análise do coeficiente de variação entre as execuções do C1 permitirá avaliar a **estabilidade do cenário baseline**, condição necessária para que as comparações com os cenários seguintes sejam estatisticamente válidas.
336+
337+
### 12.2 Rastreabilidade
338+
339+
Cada execução do workflow registra o `commit_sha` e o `run_id` no CSV de métricas. Essa informação garante **rastreabilidade total** entre os dados coletados e o estado exato do código e do ambiente em que foram produzidos.
340+
341+
### 12.3 Replicabilidade
342+
343+
A utilização do GitHub-hosted runner, combinada com a criação de um cluster Kubernetes efêmero via kind, garante que o ambiente de cada execução seja **equivalente e reprodutível**. Isso é um requisito fundamental para a validade dos dados experimentais e para a possibilidade de replicação do experimento por outros pesquisadores.
344+
345+
### 15.4 Limitações Conhecidas
346+
347+
- Os tempos de execução no GitHub-hosted runner podem apresentar variação em função da carga nos servidores do GitHub. Essa variação será mitigada pelo uso de estatísticas descritivas sobre múltiplas execuções.
348+
- O cluster kind criado no runner é de nó único e não representa um ambiente Kubernetes de produção. Essa limitação é aceitável no contexto deste experimento, cujo foco é a comparação relativa entre cenários, e não a avaliação de desempenho em escala.
349+
350+
---
351+
352+
## 13. Resumo da Etapa
353+
354+
O **Cenário C1 — Pipeline Baseline** estabelece a **linha de base experimental** do trabalho de conclusão de curso. Nesta etapa, foi implementado um pipeline CI/CD completo e funcional, abrangendo as etapas de teste, containerização e deploy em Kubernetes, sem a adição de qualquer ferramenta de análise de segurança.
355+
356+
A principal contribuição desta etapa para a pesquisa é a definição de um **tempo de referência mensurável e reprodutível**, a partir do qual será possível quantificar, com rigor, o impacto de cada prática DevSecOps introduzida nos cenários seguintes. Sem o C1, não seria possível isolar a contribuição individual de ferramentas como SonarQube, Trivy e OWASP ZAP no lead time do pipeline.
357+
358+
Os dados coletados nas cinco execuções oficiais do C1 formarão o conjunto de referência que fundamentará as análises comparativas de toda a pesquisa experimental.
359+
360+
---
361+
362+
*Documento gerado como parte da documentação técnica do TCC:*
363+
**"Avaliação Experimental do Impacto de Práticas DevSecOps no Lead Time de Pipelines CI/CD"**

0 commit comments

Comments
 (0)