MODULO 1.5

🔒 Seguranca e Permissoes

Aprenda a criar skills seguras com controle de acesso adequado, sandboxing e limites bem definidos para proteger usuarios e sistemas.

6
Topicos
40
Minutos
Intermed.
Nivel
Teoria
Tipo
1

🛡️ Principios de Seguranca

Skills operam com privilegios significativos - podem executar comandos, ler/escrever arquivos e acessar APIs. Seguranca nao e opcional.

🔐 Principios Fundamentais

  • 1. Menor Privilegio: Solicite apenas as permissoes necessarias
  • 2. Defesa em Profundidade: Multiplas camadas de protecao
  • 3. Fail-Safe: Em caso de erro, va para estado seguro
  • 4. Transparencia: Deixe claro o que a skill faz
  • 5. Auditabilidade: Acoes devem ser rastreaveis

📊 Riscos de Skills Mal Projetadas

  • Vazamento de dados: Skills podem ler arquivos sensiveis
  • Execucao maliciosa: Comandos destrutivos ou malware
  • Escalacao de privilegio: Acesso alem do necessario
  • Exfiltracao: Envio de dados para terceiros

⚠️ Lembre-se

Uma skill de terceiros pode conter codigo malicioso. Sempre revise skills antes de instalar, especialmente se pedem permissoes amplas como Bash(*).

2

🔧 Sistema de allowed-tools

O campo allowed-tools no frontmatter controla quais tools a skill pode usar. E a principal forma de limitar permissoes.

Sintaxe de allowed-tools

---
name: minha-skill
allowed-tools: Tool1, Tool2(param:valor), Tool3(*)
---

# Exemplos de patterns:

Read              # Tool sem restricao
Bash(git:*)       # Bash apenas para comandos git
Bash(npm:install) # Bash apenas para npm install
Write(*.md)       # Write apenas para arquivos .md
mcp__github__*    # Todas as tools do MCP github

✓ Permissoes Restritas (Recomendado)

allowed-tools:
  Read,
  Bash(git:status),
  Bash(git:log)

Apenas leitura e comandos git especificos

✗ Permissoes Amplas (Perigoso)

allowed-tools:
  Bash(*),
  Write(*),
  Edit(*)

Pode executar QUALQUER comando

💡 Dica de Seguranca

Se sua skill nao precisa escrever arquivos, nao inclua Write/Edit. Se so precisa de git, restrinja Bash apenas a comandos git. Cada tool nao listada e uma tool que nao pode ser abusada.

3

📁 Controle de Acesso a Arquivos

Alem de tools, e importante controlar quais arquivos a skill pode acessar. Isso previne vazamento de dados sensiveis.

📋 Arquivos Sensiveis Comuns

Credenciais

  • • .env - variaveis de ambiente
  • • *.pem, *.key - chaves privadas
  • • credentials.json - APIs
  • • ~/.ssh/* - chaves SSH

Dados Pessoais

  • • ~/.aws/credentials
  • • ~/.gitconfig com tokens
  • • ~/.npmrc com tokens
  • • Browser cookies/passwords
1

Especificar Paths Permitidos

## Restricoes
Esta skill deve operar APENAS em:
- /projeto/src/
- /projeto/tests/
NAO acesse: /, ~/, /etc/, .env
2

Usar .gitignore como Guia

Se esta no .gitignore, provavelmente nao deve ser acessado pela skill

3

Validar Antes de Ler

## Antes de ler arquivos
1. Verifique se path esta dentro do projeto
2. NAO leia arquivos .env, .pem, credentials
3. Confirme com usuario se necessario
4

🏖️ Sandboxing e Isolamento

Sandboxing limita o ambiente onde a skill opera, prevenindo que erros ou acoes maliciosas afetem o sistema.

🐳 Container/Docker

Isolamento completo do sistema

  • • Filesystem isolado
  • • Network controlada
  • • Recursos limitados
  • • Facil de destruir/recriar

📁 Diretorio Temporario

Operacoes em /tmp isolado

  • • Criar: mktemp -d
  • • Operar dentro do dir
  • • Limpar ao finalizar
  • • Nao afeta projeto real

👤 Usuario Restrito

Rodar como user sem privilegios

  • • Sem acesso root
  • • Home directory limitado
  • • Sem sudo
  • • Permissoes minimas

🔒 Modo Dry-Run

Simular sem executar

  • • Mostrar o que faria
  • • Usuario confirma
  • • Entao executa de fato
  • • Bom para acoes destrutivas

📋 Implementando Dry-Run 

## Modo de Operacao

Para acoes destrutivas (delete, overwrite, format):

1. SEMPRE mostrar preview primeiro:
   "Vou deletar os seguintes arquivos:
   - /tmp/file1.txt
   - /tmp/file2.txt
   Confirma? (s/n)"

2. Aguardar confirmacao explicita
3. So entao executar a acao
4. Reportar resultado
5

⏱️ Limites e Rate Limiting

Skills devem ter limites claros para evitar loops infinitos, consumo excessivo de recursos ou abuso de APIs.

📊 Tipos de Limites

Por Execucao

  • • Max arquivos processados: 100
  • • Max linhas por arquivo: 10000
  • • Timeout de comando: 60s
  • • Max iteracoes de loop: 50

Por Sessao

  • • Max API calls: 100/hora
  • • Max dados transferidos: 10MB
  • • Max arquivos criados: 50
  • • Max comandos Bash: 200

Definindo Limites na Skill

## Limites de Seguranca

Esta skill opera com os seguintes limites:

### Processamento
- Maximo 100 arquivos por operacao
- Arquivos maiores que 1MB serao ignorados
- Timeout de 30 segundos por comando

### API Externa
- Maximo 10 requests por minuto
- Retry com backoff exponencial (max 3x)
- Falha silenciosa apos limite

### Output
- Maximo 500 linhas de resposta
- Truncar com "[... N linhas omitidas]"

✓ Protecoes

  • ✓ Timeout em todo comando Bash
  • ✓ Contador de iteracoes em loops
  • ✓ Validacao de tamanho de input

✗ Riscos

  • ✗ Loops sem condicao de saida
  • ✗ Processar arquivos de qualquer tamanho
  • ✗ APIs sem rate limiting
6

📋 Auditoria e Logging

Skills devem ser auditaveis. Isso significa registrar acoes importantes para posterior analise e debugging.

📝 O que Logar

  • • Acoes destrutivas: Deletes, overwrites, reformats
  • • Acessos sensiveis: Arquivos de config, credenciais
  • • Chamadas externas: APIs, webhooks, network
  • • Erros: Falhas, excecoes, timeouts
  • • Decisoes: Por que uma acao foi tomada

Formato de Log Sugerido

[2026-01-20 14:32:15] INFO Skill 'code-analyzer' iniciada
[2026-01-20 14:32:16] INFO Lendo arquivos em /projeto/src (23 arquivos)
[2026-01-20 14:32:18] WARN Arquivo grande ignorado: bundle.js (2.3MB)
[2026-01-20 14:32:20] INFO Analise completa: 5 issues encontrados
[2026-01-20 14:32:21] ACTION Escrevendo report.md
[2026-01-20 14:32:21] INFO Skill finalizada com sucesso

💡 Dica de Implementacao

Instrua a skill a reportar acoes importantes no output. Isso cria um log natural da sessao que o usuario pode revisar.

Checklist de Seguranca

  • ☐ allowed-tools minimas
  • ☐ Paths restritos documentados
  • ☐ Timeouts configurados
  • ☐ Limites de processamento
  • ☐ Confirmacao para destrutivos
  • ☐ Acoes logadas claramente

🚀 Proximo Passo

Com seguranca dominada, o proximo modulo ensina Debugging e Logging - como identificar e resolver problemas em skills.

📚 Resumo do Modulo

✓
Principios - Menor privilegio, defesa em profundidade, fail-safe
✓
allowed-tools - Restrinja tools ao minimo necessario
✓
Acesso a Arquivos - Evite .env, credenciais, paths sensiveis
✓
Sandboxing - Containers, dirs temporarios, dry-run
✓
Limites - Timeouts, max iteracoes, rate limiting
✓
Auditoria - Logar acoes destrutivas e acessos sensiveis

Proximo Modulo:

1.6 - Debugging e Logging

← Modulo Anterior Proximo Modulo →