Secure Notes API

Projeto-base do curso SecDevOps: Da Teoria ao Deploy Seguro, do Coisa de Dev Academy.

Uma API mínima de notas, em FastAPI, usada para demonstrar práticas de DevSecOps num fluxo realista de desenvolvimento — do código ao container, passando pelo pipeline.

⚠️ Este repositório contém vulnerabilidades plantadas de propósito. Ele é material didático: as falhas existem para serem encontradas, explicadas e corrigidas em aula. Não use este código como base para uma aplicação real. A seção Falhas plantadas lista cada uma.

Tecnologias

• Python 3.11
• FastAPI + Uvicorn
• python-dotenv
• Docker
• GitHub Actions (pytest + pip-audit)

Como executar localmente

Crie e ative um ambiente virtual:

python -m venv .venv
source .venv/bin/activate      # Linux / macOS
.venv\Scripts\activate         # Windows

Instale as dependências:

pip install -r requirements.txt

Crie seu arquivo de ambiente a partir do exemplo:

cp .env.example .env

Suba a aplicação:

PYTHONPATH=. uvicorn app.main:app --reload

A API sobe em http://127.0.0.1:8000. A documentação interativa gerada pelo FastAPI fica em http://127.0.0.1:8000/docs.

Executar com Docker

docker build -t secure-notes-api .
docker run -p 8000:8000 --env-file .env secure-notes-api

Rodar os testes

PYTHONPATH=. pytest

Endpoints

Método	Rota	Descrição
GET	/	Mensagem de boas-vindas e ambiente atual
GET	/health	Health check
GET	/notes	Lista todas as notas
POST	/notes	Cria uma nota (title e content obrigatórios)
GET	/debug	Dump de configuração — só com DEBUG=true

As notas ficam em memória: reiniciar o processo apaga tudo. É intencional, para manter o foco do curso em segurança e pipeline, não em persistência.

Falhas plantadas

Cada item abaixo é um exercício. A ideia é encontrar a falha, entender o impacto e propor a correção — nesta ordem.

1. /debug expõe a API_KEY

app/main.py — o endpoint devolve a chave de API em texto puro na resposta HTTP.

Endpoint de diagnóstico que vaza segredo é uma das formas mais comuns de exposição em produção. Basta alguém esquecer a flag ligada. (OWASP API8:2023 — Security Misconfiguration.)

2. DEBUG=true como padrão

.env.example — quem copia o exemplo sobe a aplicação já com o /debug liberado.

Configuração padrão deve ser a mais restritiva. O caminho seguro precisa ser o caminho preguiçoso, ou ninguém segue.

3. A API_KEY não protege nada

app/main.py — a chave é lida do ambiente, mas nenhuma rota a verifica. /notes aceita leitura e escrita de qualquer pessoa.

Segredo que existe mas não é usado dá falsa sensação de proteção — pior que não ter. (OWASP API2:2023 — Broken Authentication.)

4. O container roda como root

Dockerfile — sem USER, o processo roda com uid 0.

Se a aplicação for comprometida, o atacante começa como root dentro do container, o que encurta muito o caminho para escapar dele.

5. COPY . . sem .dockerignore

Dockerfile — tudo que estiver no diretório entra na imagem, inclusive um .env real e o .git.

Segredo dentro de imagem publicada não se apaga: fica na camada, mesmo que um RUN rm venha depois.

6. O pip-audit não bloqueia nada

.github/workflows/ci.yml — o passo de auditoria roda com continue-on-error: true.

O pipeline reporta vulnerabilidade em dependência e segue verde. Gate que não trava não é gate: é log.

Exercícios propostos

1. Proteger /notes exigindo a API_KEY num header.
2. Remover o /debug ou restringi-lo ao ambiente de desenvolvimento por verificação de APP_ENV.
3. Adicionar USER não-root ao Dockerfile e um .dockerignore.
4. Tirar o continue-on-error do pip-audit e resolver o que ele apontar.
5. Acrescentar análise estática (bandit) e varredura de imagem (trivy) ao pipeline.

Licença

MIT — veja LICENSE.