Pi Agent: Security & Project Trust

Última atualização: 2026-08-31

--- title: "Seguranca e Confianca de Projeto" description: "Entenda o modelo de seguranca do Pi Agent, incluindo controle de permissoes, confianca de projeto, sandbox de ferramentas e melhores praticas de seguranca." order: 13 lang: pt-br

Um Agent pode executar comandos para você — ou causar danos. Mecanismos de segurança são os "freios."

1. Visão Geral do Modelo de Segurança

A segurança do Pi Agent é baseada em um modelo de três camadas:

Security Three-Layer Model
├── Layer 1: Project Trust — Whether the Agent can access the project
├── Layer 2: Tool Permission — Which tools are allowed
└── Layer 3: Execution Sandbox — Security boundary for tool execution

2. Confiança de Projeto

(1) Níveis de Confiança

(2) Definir Nível de Confiança

pi-agent trust set ./my-project --level trusted
pi-agent trust list

(3) Prompt de Primeira Interação

Ao usar o Pi Agent em um novo diretório de projeto:

New project detected: /home/alice/my-project
Trust this project? [y/N]

trusted    - Full access (read/write files, execute commands)
readonly   - Read-only access
untrusted  - No access

Select trust level:

(4) API Python

from pi_agent import Agent, TrustLevel

agent = Agent(
    name="safe_agent",
    project_path="./my-project",
    trust_level=TrustLevel.READONLY
)

3. Permissões de Ferramentas

(1) Níveis de Perigo

(2) Configuração de Permissões

permissions:
  tools:
    safe: auto
    medium: confirm
    dangerous: deny

  allow:
    - calculator
    - search
    - file_reader
  deny:
    - shell
    - file_write

  confirm_dangerous: true
  confirm_file_write: true
  confirm_shell: true

(3) Confirmação em Tempo de Execução

you> Delete all temporary files
Agent wants to execute: rm -rf /tmp/project_*
Allow? [y/N/a(always)]

4. Sandbox de Execução

from pi_agent import Agent

agent = Agent(
    name="sandboxed",
    sandbox=True,
    sandbox_dir="/tmp/pi_sandbox",
    allowed_commands=["python", "pytest"],
    max_execution_time=30
)

Isolamento de sistema de arquivos:

agent = Agent(
    sandbox=True,
    sandbox_dir="./workspace/sandbox",
    allowed_paths=["./data/", "./output/"]
)

Restrições de rede:

agent = Agent(
    sandbox=True,
    network_access=False,
    allowed_domains=["api.github.com"]
)

5. Melhores Práticas de Segurança

• Chaves API em variáveis de ambiente, não em arquivos de configuração
• Adicione .pi-agent.local.yaml ao .gitignore
• Privilégio mínimo: conceda apenas permissões necessárias
• Habilite logs de auditoria

agent = Agent(
    audit_log=True,
    audit_file="./audit.log"
)

❓ Perguntas Frequentes

P: A confiança pode ser revogada? R: Sim. pi-agent trust set ./project --level untrusted ou exclua o arquivo em ~/.pi-agent/trust/. P: A ferramenta shell pode ser completamente desabilitada? R: Sim. Adicione deny: [shell] na configuração ou não a inclua na lista de ferramentas. Isso é recomendado. P: O sandboxing afeta o desempenho? R: O isolamento do sistema de arquivos tem impacto insignificante. Restrições de rede podem afetar ferramentas que precisam de internet.

❓ Resumo

• Segurança em três camadas: confiança de projeto → permissões de ferramentas → sandbox de execução
• Quatro níveis de confiança: untrusted, readonly, trusted, restricted
• Ferramentas classificadas por perigo: seguro (automático), médio (confirmar), perigoso (negar)
• Sandbox isola sistema de arquivos, restringe rede, controla tempo de execução
• Chaves API via variáveis de ambiente, privilégio mínimo, habilite logs de auditoria

📝 Exercícios

1. Básico (Dificuldade: ⭐): Defina confiança readonly para seu projeto, observe o comportamento do Agent em modo restrito.
2. Intermediário (Dificuldade: ⭐⭐): Configure um Agent com sandbox que apenas lê diretórios específicos e roda comandos Python.
3. Avançado (Dificuldade: ⭐⭐⭐): Escreva um arquivo de política de segurança com uma matriz de permissões completa, verifique via logs de auditoria.

Equipe Técnica Web-Tutorial

Uma plataforma de tutoriais mantida por diversos desenvolvedores. Cada tutorial é escrito e revisado por profissionais da área correspondente. Trabalhamos para manter nosso conteúdo preciso e confiável — se encontrar algum problema, avise-nos.

Sobre Nós