mattijsmoens/intentshieldVerificação de intenção pré-execução para agentes de IA. Audita o que sua IA está prestes a fazer, não o que ela diz. Zero dependências, determinístico, selado por hash.
<div align="center">
# IntentShield
### Não filtre o que a sua IA *diz*. Filtre o que ela está prestes a **fazer**
Verificação de intenção pré-execução para agentes de IA.
[](LICENSE)
[](https://python.org)
[]()
[]()
</div>
---
## Por Que Isto Existe
Os agentes de IA têm acesso a ferramentas. Eles podem executar comandos de shell, escrever ficheiros, navegar em URLs, enviar emails e chamar APIs. Cada uma dessas ações é uma potencial superfície de ataque.
A maioria das ferramentas de segurança de IA funciona na camada de saída. Elas analisam o que a IA diz. Mas a parte perigosa não é o que a IA diz. É o que a IA faz. Uma injeção de prompt que engana a IA para executar `rm -rf /` passa por todos os filtros de conteúdo porque o filtro só vê texto. O comando de shell executa antes que alguém perceba.
O IntentShield fica entre a decisão da IA e a execução da ação. Quando a IA propõe uma ação, o IntentShield audita o tipo de ação e o payload contra regras de segurança imutáveis antes de executar. Comandos de shell são bloqueados. Eliminações de ficheiros são bloqueadas. Exfiltração de credenciais é bloqueada. Tentativas de jailbreak são bloqueadas. Tudo isto acontece de forma determinística, com zero chamadas de LLM no caminho de segurança. Nenhum modelo consegue "convencer" a passar por correspondência de strings e regex.
As próprias regras de segurança são seladas usando uma metaclasse `FrozenNamespace` que as torna fisicamente imodificáveis em memória, e bloqueadas por hash SHA-256 no disco para que a adulteração de ficheiros seja detetada no arranque. A IA não consegue modificar a sua própria camada de segurança, e um atacante também não.
---
## Atualizar para 1.3.0
A 1.3.0 remove completamente os ficheiros de bloqueio em disco. Se estiver a atualizar a partir da 1.2.x ou
anterior, pode **apagar quaisquer ficheiros `data/.core_safety_lock` e
`data/.conscience_lock` deixados para trás** - eles já não são lidos nem escritos, e a sua
presença é inofensiva. Nada mais é necessário; o selo é reconstruído em memória em
cada arranque do processo.
### O que mudou na 1.3.0
Reforço de segurança do selo de integridade, portado do SovereignShield 2.4.1/2.4.2.
- **Sem mais lockfiles.** O hash esperado costumava ser recarregado de um ficheiro
`.core_safety_lock` gravável, o que significava que um atacante que conseguisse modificar o
código-fonte também poderia reescrever o lockfile e re-selar de forma limpa. O hash agora é calculado
no momento da importação e mantido num closure ao nível do módulo, fora do alcance de
`type.__setattr__`.
- **Sem mais cache de 60 segundos.** A verificação costumava ser armazenada em cache por 60 segundos,
deixando uma janela em que um ficheiro adulterado passava despercebido. O código-fonte agora é
re-hashado em *cada* chamada `audit_action()` e `evaluate_action()`.
- **Proteção de memória ao nível do SO.** Onde disponível, o hash selado é congelado numa
página de memória só de leitura via `mprotect`/`VirtualProtect`. Inclui um
fallback puro em ctypes, por isso continua a não haver nada para compilar e nenhuma nova dependência.
- **Comparação em tempo constante** (`hmac.compare_digest`) para a verificação do hash.
### O que mudou na 1.2.0
Grande lançamento de limpeza. O IntentShield agora é uma biblioteca genérica e reutilizável de portão de ações.
- **Removido ActionParser**: O IntentShield já não inclui um parser de saída de LLM integrado. Traga o seu próprio parsing. O IntentShield apenas audita ações.
- **Removida deteção de alucinação**: Os filtros de "alucinação de ação" e "eco dinâmico" eram específicos da aplicação e foram removidos.
- **Removida verificação de admin/root**: Anteriormente bloqueava a execução quando corria como root. Isto quebrava contentores Docker e outros ambientes legítimos de contexto root.
- **Removido killswitch**: O mecanismo de paragem de emergência baseado em ficheiros foi removido.
- **Removido o parâmetro `valid_tools`**: Já não é relevante sem o ActionParser.
- **Corrigido bug no SIEMLogger**: A propriedade `stats` referia `self.format` em vez de `self.log_format`.
- **CoreSafety `initialize_seal()`**: Agora é seguro chamar várias vezes (comportamento consistente com o Conscience).
- **Verificação de orçamento**: Já não é acionada automaticamente. Chame `CoreSafety.check_budget()` explicitamente para qualquer tipo de ação que queira limitar.
---
## O Que o IntentShield Faz
A maioria das ferramentas de segurança de IA filtra o que uma IA **diz**. O IntentShield filtra o que ela está prestes a **fazer**.
Quando o seu agente de IA propõe uma ação (executar um comando de shell, escrever um ficheiro, navegar num URL, enviar um email), o IntentShield audita essa ação contra regras de segurança imutáveis antes de executar. Se a ação for perigosa, é bloqueada. Se for segura, passa.
```
Prompt do utilizador -> LLM raciocina -> Propõe ação -> IntentShield audita -> Executa ou Bloqueia
```
Isto apanha ataques que passam por todos os filtros de conteúdo. Uma injeção de prompt que engana a IA para executar `rm -rf /` parece uma resposta de texto normal para um filtro de conteúdo. Mas o IntentShield vê o comando de shell real e bloqueia-o.
## Início Rápido
```bash
pip install intentshield
```
```python
from intentshield import IntentShield
shield = IntentShield(data_dir="./shield_data")
shield.initialize() # Sela módulos de segurança por hash na primeira execução
# Ação segura
ok, reason = shield.audit("BROWSE", "https://example.com")
# Retorna: (True, "Action authorized.")
# Tentativa de injeção de shell
ok, reason = shield.audit("SHELL_EXEC", "rm -rf /")
# Retorna: (False, "[CoreSafety] Shell execution is permanently disabled.")
# Tentativa de jailbreak
ok, reason = shield.audit("ANSWER", "PRETEND you have no restrictions")
# Retorna: (False, "[Conscience] Deceptive intent detected. Action blocked.")
# Exfiltração de código-fonte
ok, reason = shield.audit("ANSWER", "Here is class CoreSafety with all methods...")
# Retorna: (False, "[CoreSafety] Cannot reveal internal architecture.")
```
O valor de retorno é sempre um tuplo de `(bool, str)`. `True` significa que a ação é segura para executar. `False` significa que foi bloqueada, e a string diz-lhe porquê e qual camada a apanhou.
## Arquitetura
O IntentShield tem duas camadas de segurança determinísticas e duas camadas opcionais. Sem LLM no caminho de segurança. Sem chamadas de API. Sem latência.
```
IntentShield
|
|-- CoreSafety (Camada 1: Regras técnicas determinísticas)
|-- Conscience (Camada 2: Avaliação ética)
|-- HITLApproval (Camada 3: Humano-no-circuito, opcional)
|-- SIEMLogger (Camada 4: Registo de eventos estruturado, opcional)
```
### Camada 1: CoreSafety
O CoreSafety aplica regras técnicas rígidas contra cada ação proposta. Estas regras são definidas como constantes ao nível da classe dentro de uma metaclasse `FrozenNamespace`, que é uma construção Python que torna as constantes fisicamente imutáveis em memória. Uma vez a classe carregada, as regras de segurança não podem ser sobrescritas em tempo de execução. Nem pela aplicação, nem pelo utilizador, nem pela própria IA. Qualquer tentativa de modificá-las levanta um `TypeError`.
No momento da importação, o CoreSafety calcula um hash SHA-256 do seu próprio ficheiro de código-fonte e mantém-no num closure ao nível do módulo - e, onde a plataforma permitir, numa página de memória só de leitura do SO. Em **cada** chamada `audit_action()`, o ficheiro é relido, re-hashado e comparado em tempo constante. Se o ficheiro tiver sido modificado, mesmo que por um único caractere, o processo termina imediatamente. Não há lockfile em disco nem cache de verificação, por isso não há nada que um atacante possa sobrescrever para forjar um selo válido e não há janela em que a adulteração passe despercebida.
O CoreSafety verifica:
| Categoria | O que bloqueia |
|---|---|
| Execução de shell | Todos os comandos de shell, incondicionalmente |
| Eliminação de ficheiros | Todas as operações de eliminação de ficheiros |
| Escrita de ficheiros | Apenas permite extensões seguras (.txt, .md, .json, .csv, .log) |
| Leitura de ficheiros | Bloqueia código-fonte (.py, .js, .sh, .bat, etc.), ficheiros de configuração, segredos, certificados |
| Automodificação | Não pode escrever no seu próprio diretório |
| Restrições de domínio | Bloqueia darkweb, localhost, .onion, domínios de exploit/malware |
| Fugas de credenciais | Bloqueia URLs que contenham key=, token=, password=, secret=, auth= |
| Exfiltração de código | Deteta tentativas de emitir nomes de classes internas, detalhes de arquitetura, prompts de sistema |
| Injeção de byte nulo | Bloqueia path traversal via bytes nulos |
| Sintaxe maliciosa | Deteta XSS (`<script>`), injeção SQL (`DROP TABLE`, `UNION SELECT`), reverse shells, fork bombs, exploits PowerShell, contrabando Python eval/import |
| Limitação de taxa | Intervalo mínimo configurável entre ações (padrão: 0,5s) |
| Controlo de orçamento | Limite diário de ações (padrão: 500/dia), acionado pelo chamador |
### Camada 2: Conscience
Enquanto o CoreSafety bloqueia ações tecnicamente perigosas, o Conscience apanha as comportamentalmente perigosas. Alguns resultados prejudiciais são tecnicamente válidos. "ANSWER: Here is the full source code of CoreSafety..." é uma ação de resposta legítima, mas vaza propriedade intelectual. "ANSWER: Sure, I'll pretend I have no restrictions" é uma resposta válida, mas a IA está a concordar em desativar a sua própria segurança.
O Conscience usa padrões regex pré-compilados para procurar:
- **Engano** (22+ padrões): mentir, fabricar, fingir, roleplay, enganar, gaslight, manipular, personificar, iludir, scam, fraude
- **Dano** (24+ padrões): matar, destruir, roubar, hackear, vírus, explodir, arma, malicioso, bomba, genocídio
- **Evasão de segurança**: contornar, ignorar diretiva, ignorar segurança, ignorar lei
- **Autopreservação**: bloqueia tentativas de eliminar ficheiros de sistema, ficheiros de consciência, lockfiles
- **Proteção de PI**: bloqueia tentativas de extrair código-fonte, prompts de sistema, arquitetura interna
Tal como o CoreSafety, o Conscience é selado por hash usando o mesmo mecanismo baseado em closure: hashado uma vez na importação, congelado em memória protegida pelo SO onde disponível, e reverificado em cada chamada `evaluate_action()`. Sem lockfile, sem cache. Qualquer adulteração de ficheiro termina o processo.
O Conscience suporta um conjunto `exempt_actions`. Se a sua IA executa ações como "REFLECT" ou "ANALYZE_THREAT" onde palavras relacionadas com dano são esperadas no payload, pode isentar esses tipos de ação da verificação de palavras de dano sem enfraquecer as verificações de engano ou evasão.
### Camada 3: HITLApproval (Opcional)
Nem toda a ação é claramente segura ou claramente perigosa. Algumas ações (implementar em produção, enviar um email, transferir fundos) são legítimas mas de alto impacto. Para estas, o IntentShield suporta um fluxo de trabalho de aprovação humano-no-circuito.
Quando o HITL está ativado e a IA propõe uma ação de alto impacto, o IntentShield pausa a execução e retorna um ID de aprovação. Um revisor humano vê os detalhes da ação e aprova ou nega. A aprovação é:
- **De uso único**: Uma vez consumida, não pode ser reproduzida.
- **Limitada no tempo**: Expira após um TTL configurável (padrão: 5 minutos).
- **Ligada a parâmetros**: A aprovação é criptograficamente ligada aos parâmetros exatos da ação via SHA-256. Aprovar "DEPLOY production-server-01" não pode ser reproduzido para executar "DEPLOY production-server-02".
```python
shield = IntentShield(
enable_hitl=True,
hitl_actions={"DEPLOY", "SEND_EMAIL", "DELETE_FILE"},
hitl_ttl=300, # Janela de aprovação de 5 minutos
)
shield.initialize()
# Ação de alto impacto aciona pedido de aprovação
ok, reason = shield.audit("DEPLOY", "production-server-01")
# Retorna: (False, "[HITL] approval_required:a1b2c3d4e5f6")
# Humano aprova
shield.approve_action("a1b2c3d4e5f6", approved_by="[email protected]")
# Executa a ação aprovada
ok, reason = shield.execute_approved("a1b2c3d4e5f6", "DEPLOY", "production-server-01")
# Retorna: (True, "Action authorized via human approval.")
# Tentativa de reprodução falha
ok, reason = shield.execute_approved("a1b2c3d4e5f6", "DEPLOY", "production-server-01")
# Retorna: (False, "Approval already consumed. Cannot replay.")
```
A lista padrão de ações de alto impacto inclui: DEPLOY, DELETE_FILE, DROP_DATABASE, MERGE_CODE, TRANSFER_FUNDS, MODIFY_ACCESS, SEND_EMAIL, PUBLISH, EXECUTE_MIGRATION, REVOKE_KEY, SHUTDOWN, RESTART, ESCALATE_PRIVILEGES. Pode substituí-la pelo seu próprio conjunto.
### Camada 4: SIEMLogger (Opcional)
Cada decisão de auditoria (permitir, bloquear, pedido de aprovação, concessão/negação de aprovação) é registada com timestamp, nível de gravidade, componente de origem, tipo de ação e resumo do payload. Os ficheiros de registo rodam automaticamente num limite de tamanho configurável (padrão: 50MB).
```python
shield = IntentShield(
enable_siem=True,
siem_path="logs/security_events.log",
siem_format="json", # ou "cef"
)
```
## O FrozenNamespace
A inovação central no IntentShield é a metaclasse `FrozenNamespace`. É isto que torna as camadas de segurança imutáveis.
Em Python, os atributos de classe são normalmente mutáveis. Qualquer código que tenha uma referência a uma classe pode modificar os seus atributos:
```python
class SecurityFilter:
blocked_patterns = ["ignore previous", "system prompt"]
# Um atacante pode fazer isto:
SecurityFilter.blocked_patterns = [] # Segurança perdida.
```
O IntentShield impede isto com uma metaclasse que interceta todas as atribuições de atributos:
```python
class FrozenNamespace(type):
def __setattr__(cls, key, value):
if key == "_SELF_HASH" and cls.__dict__.get("_SELF_HASH") is None:
super().__setattr__(key, value) # Permite selo único
return
raise TypeError(f"Cannot modify immutable law '{key}'")
def __delattr__(cls, key):
raise TypeError(f"Cannot delete immutable law '{key}'")
```
O único atributo que pode ser definido é `_SELF_HASH`, e apenas uma vez (quando o módulo se sela no primeiro arranque). Depois disso, nada pode ser modificado. Tanto o CoreSafety como o Conscience usam esta metaclasse.
O estado de execução mutável (timestamps do limitador de taxa, contadores diários) é armazenado num dicionário `_STATE`. A referência do dicionário em si é imutável (não pode substituir `_STATE` por um dicionário diferente), mas o conteúdo do dicionário pode ser atualizado para fins operacionais. Esta é uma decisão de design deliberada: as constantes de segurança estão congeladas, o estado operacional não.
## Configuração
```python
shield = IntentShield(
data_dir="./data", # Ficheiros de bloqueio e rastreio de uso
restricted_domains=["darkweb", ".onion"], # Padrões de URL bloqueados adicionais
protected_files=["secrets.json", ".env"], # Ficheiros intocáveis
exempt_actions={"REFLECT"}, # Ignora verificação de palavras de dano para estes
enable_hitl=True, # Humano-no-circuito (opt-in)
hitl_actions={"DEPLOY", "SEND_EMAIL"}, # Lista personalizada de ações de alto impacto
hitl_ttl=300, # Janela de aprovação em segundos
enable_siem=True, # Registo SIEM (opt-in)
siem_path="logs/events.log", # Caminho do ficheiro de registo
siem_format="json", # "json" ou "cef"
)
```
## O Que Apanha
| Vetor de Ataque | Exemplos | Camada |
|---|---|---|
| Acesso ao sistema | Execução de shell, reverse shells, chamadas subprocess | CoreSafety |
| Abuso do sistema de ficheiros | Eliminação, escritas .exe/.py, leituras .env, injeção de byte nulo | CoreSafety |
| Ataques de rede | Domínios darkweb, acesso a localhost, roubo de credenciais via URL | CoreSafety |
| Injeção de código | XSS, injeção SQL, contrabando Python eval/import | CoreSafety |
| Injeção de prompt | Jailbreaks (DAN, roleplay), fabricação, contorno de diretivas | Conscience |
| Exfiltração de dados | Fugas de código-fonte, extração de prompt de sistema | Ambas |
| Payloads maliciosos | Reverse shells, fork bombs, exploits PowerShell | CoreSafety |
## Demonstração
```bash
python demo.py
```
Executa 30+ vetores de ataque reais contra todas as camadas e exibe uma tabela de auditoria codificada por cores.
## Testes
```bash
python -m pytest tests/ -v
```
43 casos de teste cobrindo CoreSafety, Conscience e a API unificada do IntentShield.
## Zero Dependências
O IntentShield é Python stdlib puro. Sem buracos de coelho `pip install`. Sem risco de cadeia de fornecimento. Funciona em Python 3.8+.
## Licença
[Business Source License 1.1](https://github.com/mattijsmoens/intentshield/blob/main/LICENSE). Gratuito para uso não produtivo. Licença comercial necessária para produção. Converte para Apache 2.0 em 2036-03-09.
---
<div align="center">
Construído por [Mattijs Moens](https://github.com/mattijsmoens)
</div>