As Proteções de Stonevale

[!NOTE] Status: Conteúdo pronto · Mídia: Capa gerada e ilustração SVG original · Última verificação: 2026-09-05
Capacidade principal: Limitar autoridade e operações arriscadas

[!TIP] Baixe este kit de aprendizagem e use o guia de extração e configuração. Mantenha o starter original intacto.

---
config:
  theme: base
  look: classic
  themeVariables:
    darkMode: false
    background: "#ffffff"
    primaryColor: "#f5f5f5"
    primaryTextColor: "#111111"
    primaryBorderColor: "#555555"
    secondaryColor: "#e0e0e0"
    secondaryTextColor: "#111111"
    secondaryBorderColor: "#666666"
    tertiaryColor: "#bdbdbd"
    tertiaryTextColor: "#111111"
    tertiaryBorderColor: "#444444"
    lineColor: "#444444"
    textColor: "#111111"
    mainBkg: "#f5f5f5"
    nodeBorder: "#555555"
    clusterBkg: "#ffffff"
    clusterBorder: "#999999"
    edgeLabelBackground: "#ffffff"
    actorBkg: "#e0e0e0"
    actorBorder: "#555555"
    actorTextColor: "#111111"
    actorLineColor: "#777777"
    signalColor: "#333333"
    signalTextColor: "#111111"
    labelBoxBkgColor: "#f5f5f5"
    labelBoxBorderColor: "#777777"
    labelTextColor: "#111111"
    loopTextColor: "#111111"
    activationBkgColor: "#bdbdbd"
    activationBorderColor: "#555555"
    noteBkgColor: "#f5f5f5"
    noteTextColor: "#111111"
    noteBorderColor: "#777777"
    attributeBackgroundColorOdd: "#f5f5f5"
    attributeBackgroundColorEven: "#e0e0e0"
---
flowchart LR
    accTitle: Mapa de capacidades de The Guardrails of Stonevale
    accDescr: Uma função determinística pode verificar sintaxe sem executá-la. Seus testes aprovados não estabelecem um sandbox de comandos de produção.
    X["Texto externo ou comando proposto"] --> P["Analisar como dados não confiáveis"]
    P --> D{"Forma exata permitida?"}
    D -->|Não| R["Rejeitar explicitamente"]
    D -->|Sim| A["Retornar decisão permitida"]
    A -. "Integração separada" .-> H["Hook de ciclo de vida revisado"]

Legenda. As setas sólidas são avaliação de política local. A aresta tracejada marca uma integração opcional que este verificador não instala.

Explicação. Uma função determinística pode verificar sintaxe sem executá-la. Seus testes aprovados não estabelecem um sandbox de comandos de produção.

Referências oficiais

Estas fontes oficiais são a autoridade sobre o comportamento e a disponibilidade do produto. Consulte-as novamente ao usar uma superfície diferente ou após uma atualização do produto.

• Hooks de agentes no VS Code — versão prévia (Preview)
• Referência de hooks
• Hooks do GitHub Copilot

História

As pontes de Stonevale são seguras porque portões, limites de peso e sentinelas contêm os erros antes que cheguem ao abismo.

A fantasia é um recurso de memorização; a lição de engenharia exige evidências observáveis e reproduzíveis.

Objetivos de aprendizagem

• Implemente uma lista permitida para os dois comandos Node locais permitidos.
• Rejeite operadores, travessia, caminhos absolutos e argumentos extras como dados, sem executá-los.
• Explique a diferença entre uma regra instrucional, uma função de política e um hook ao vivo.

Pré-requisitos

Para preparar ferramentas e contas pessoais, conclua o guia de pré-requisitos. Para estudar somente pelo terminal, siga o fluxo via CLI no kit extraído; as evidências específicas do VS Code continuam separadas.

Limite de evidência: Esta função não está instalada como um hook ao vivo. O suporte a hooks está em versão Prévia e qualquer instalação requer uma configuração revisada separada.

Duração estimada da sessão: 45–75 minutos após os pré-requisitos; a duração real varia. Nunca use segredos de produção nem dados de clientes.

Explicação dos conceitos

As proteções combinam permissões do host, restrições de ferramentas, proteções do repositório, credenciais com escopo definido, verificações determinísticas e revisão humana. As instruções melhoram o comportamento, mas não são um limite de segurança. Trate o conteúdo externo e a saída das ferramentas como dados não confiáveis. Nunca exponha segredos. Hooks podem adicionar verificações determinísticas do ciclo de vida onde houver suporte, mas esse comportamento pode estar em versão prévia (Preview) e deve ser identificado e testado.

Caso de uso concreto

A política recebe uma string de comando e devolve uma decisão. Uma string que contém operadores de shell é uma entrada de teste rejeitada, nunca um comando que este exercício pede para você executar.

Verificação de vocabulário

• Papel: Ask, Plan, Agent ou um agente personalizado.
• Harness/superfície: o runtime ou a superfície do produto em que um papel opera.
• Destino: o destino de sessão selecionado, como Local, Copilot ou Cloud, quando exposto.
• Ambiente: a pasta, worktree, máquina local, Codespace ou ambiente remoto.
• Instruções: contexto duradouro aplicado automaticamente.
• Prompt: um modelo de tarefa invocado manualmente.
• Skill: conhecimento especializado reutilizável, carregado quando relevante.
• Agente personalizado: um papel com instruções, ferramentas e transferências opcionais.
• MCP: Model Context Protocol.
• Evidência: um caminho, diff, resultado de comando, rastreamento ou decisão de revisão.

Fluxo de trabalho Ask → Plan → Agent

Ask — investigar

1. Identifique o resultado real esperado pelo usuário e a fonte de verdade atual.
2. Inspecione os arquivos, as instruções, as ferramentas, as permissões e as verificações existentes relevantes.
3. Cite caminhos concretos ou evidências da plataforma para cada descoberta importante.
4. Registre as incertezas e não deduza capacidades indisponíveis.

Ponto de controle: Nenhuma implementação antes de compreender o estado atual e as evidências.

Plan — projetar

1. Declare o escopo, o que está fora dele, as suposições, os riscos e os limites de confiança.
2. Selecione o mínimo necessário de papel, ferramentas, autoridade e ambiente.
3. Defina critérios de aceitação, comandos de verificação, revisão e restauração.
4. Sinalize qualquer dependência em versão prévia (Preview) ou experimental e forneça uma alternativa.

Ponto de controle: Outra pessoa em aprendizagem deve conseguir prever a conclusão a partir do plano.

Agent — executar

1. Faça a menor alteração reversível ou produza o artefato planejado.
2. Use ciclos curtos de inspecionar → alterar → verificar.
3. Preserve a saída dos comandos, o status de saída, os diffs, os rastreamentos ou os registros da plataforma.
4. Pare quando os critérios de aceitação forem atendidos; não faça limpezas sem relação com a tarefa.

Revisão — questionar

1. Inspecione o diff ou artefato completo.
2. Compare cada resultado com o plano e os critérios de aceitação.
3. Execute a verificação existente mais restrita e relevante, ampliando-a somente quando houver justificativa.
4. Registre as limitações e os riscos não resolvidos.
5. Avalie o trabalho com rubric.md.

Missão guiada

1. Prepare uma cópia isolada

1. Baixe e extraia o kit stonevale-guardrails em um novo diretório de trabalho.
2. Leia KIT-START.md em sua raiz. Abra starter/ como o workspace do VS Code quando testar a descoberta, mas execute o verificador a partir da raiz do kit.
3. Inspecione starter/guard.js, verify.js antes de editar.
4. A partir da raiz do kit extraído, execute node verify.js.
5. Registre a rejeição documentada do starter. Um runtime ausente ou uma falha não relacionada não é o resultado esperado do exercício.

2. Investigue e planeje

Comando da verificação inicial pronto para copiar, a partir da raiz do kit extraído:

node verify.js

Em Ask, solicite um rastreamento dos arquivos inspecionados e do que o verificador realmente observa. Questione qualquer afirmação sobre execução ao vivo que não esteja respaldada pela saída.

Use este prompt de planejamento:

Specify exact allowed executable/script pairs and all rejected forms. Keep test inputs as strings; implement no shell execution. State the boolean behavior for empty and wrong-type input.
Do not implement yet. Identify affected files, the negative case and a safe reset.

3. Implemente o recorte revisado

1. Aprove apenas o artefato starter nomeado e os testes focados necessários.
2. Peça a Agent para implementar um único recorte; inspecione os comandos propostos antes da execução.
3. Execute node verify.js novamente a partir da raiz do kit, ou node ../verify.js a partir de starter/.
4. Compare o resultado exato com o ponto de verificação abaixo e revise o diff completo.
5. Registre separadamente a descoberta do host ou a atividade ao vivo quando disponível. Não habilite serviços extras para fabricar um resultado aprovado.

[!IMPORTANT] Ponto de verificação: Apenas os dois scripts nomeados são permitidos; as strings inseguras fornecidas são rejeitadas sem execução. Esta função não está instalada como um hook ao vivo. O suporte a hooks está em versão Prévia e qualquer instalação requer uma configuração revisada separada.

4. Comprove que uma verificação pode rejeitar um erro

Permita temporariamente um argumento extra e confirme que o caso correspondente falha. Restaure a lista permitida.

Termine com a evidência de capacidade específica da aventura na rubrica, não apenas com a presença de um arquivo.

Falha intencional: O Pergaminho Amigável

Faça isso somente em um ambiente descartável:

Deixe um agente com privilégios excessivos processar um texto de issue que se parece com instruções sem identificá-lo como não confiável. O limite de confiança se desfaz e ações de ferramentas sem relação com a tarefa se tornam possíveis.

Recuperação

Retorne a Ask, identifique o limite violado, restrinja o plano, remova autoridade ou contexto desnecessários e repita a menor verificação relevante. Documente a lição sobre a causa, em vez de apenas afirmar que a tentativa falhou.

Desafio independente

Elabore proteções para atualizações de dependências que proíbam publicação, rotação de segredos, implantação e mesclagem.

Restrições:

• Não copie a missão guiada literalmente.
• Não adicione ferramentas, permissões ou recursos de nuvem sem uma necessidade declarada.
• Não faça alegações de qualidade, desempenho, compatibilidade ou disponibilidade sem evidências obtidas por execução.
• Mantenha a linguagem de fantasia subordinada à clareza técnica.

Lista de verificação de evidências

• Descobertas de Ask fundamentadas nas fontes.
• Plano aprovado com escopo, exclusões, riscos, verificações e restauração.
• Diff ou artefato de Agent limitado ao escopo declarado.
• Saída de verificação com comando, status ou registro da plataforma.
• Causa raiz da falha intencional e recuperação.
• Resultado do desafio independente.
• Limitações explícitas e notas sobre o status das funcionalidades.
• rubric.md preenchido.

Instruções de restauração

1. Salve seu diff, a saída do comando e as limitações do kit descartável.
2. Pare apenas o processo ou a sessão de aprendizagem que você iniciou. Não pare outros projetos.
3. Se você inicializou Git no kit, inspecione git status --short lá e restaure apenas os seus arquivos de exercício nomeados a partir da baseline local.
4. Caso contrário, extraia o ZIP original em um novo diretório não utilizado para outra tentativa; não sobrescreva seu trabalho atual.
5. Remova apenas configurações, worktrees ou recursos remotos pertencentes ao exercício depois de revisar o que vale a pena preservar.

A fonte do currículo e os demais projetos devem permanecer inalterados. Uma redefinição da cópia do kit não é um reset completo do repositório.

Próxima aventura

O Cartógrafo MCP