GhostRunner / C2 Agent - Remote Execution Agent over Mutual TLS

Aviso de uso responsável: Este software é destinado exclusivamente a ambientes de laboratório, exercícios de red team autorizados e fins educacionais. A execução em sistemas sem autorização explícita do proprietário é ilegal e antiética. O autor não se responsabiliza por uso indevido.

---

Visão Geral

C2 Agent é um agente de execução remota de comandos que implementa o lado cliente (implant) de uma arquitetura Command & Control (C2) minimalista. O agente estabelece uma conexão de saída (reverse connection) com um servidor controlador, autentica-se via token HMAC e aguarda instruções para execução local de comandos dentro de um conjunto pré-aprovado (allowlist).

O projeto foi desenvolvido com foco em três pilares:

Pilar	Mecanismo
Confidencialidade	TLS 1.3 com verificação de CA configurável
Integridade	Assinatura HMAC-SHA256 por mensagem
Autenticidade	Token Bearer com comparação em tempo constante

---

Arquitetura

                          ┌─────────────────────────────────────────────────────┐
                          │                    SERVIDOR C2                      │
                          │           (não incluso neste repositório)           │
                          └─────────────────────────┬───────────────────────────┘
                                                    │  TLS 1.3 
                                                    │  JSON-Lines over TCP
                                                    ▼
                          ┌─────────────────────────────────────────────────────┐
                          │                   C2 AGENT (este código)            │
                          │                                                     │
                          │  ┌──────────┐   ┌───────────┐   ┌────────────────┐  │
                          │  │  TLS/TCP │──▶│  Session  │──▶│  Command       │ │
                          │  │  Layer   │   │  Manager  │   │  Dispatcher    │  │
                          │  └──────────┘   └───────────┘   └────────┬───────┘  │
                          │                                          │          │
                          │                                 ┌────────▼───────┐  │
                          │                                 │   Allowlist    │  │
                          │                                 │   Executor     │  │
                          │                                 └────────────────┘  │
                          └─────────────────────────────────────────────────────┘

---

Decisões de Design

Protocolo JSON-Lines com Envelope Assinado

Cada mensagem trafega como uma única linha JSON contendo dois campos: body (payload serializado) e sig (assinatura HMAC-SHA256 do body). Isso permite:

• Parsing incremental sem buffer de estado complexo;
• Verificação de integridade independente da camada TLS;
• Defesa em profundidade (defense in depth): mesmo que a sessão TLS seja comprometida por um proxy intermediário, mensagens adulteradas são rejeitadas.

Allowlist de Comandos

O agente não expõe um shell genérico. A execução é delegada exclusivamente a comandos presentes em _ALLOWLIST, sem uso de shell=True. Isso mitiga:

• Injeção de comandos via argumentos maliciosos;
• Escalada de escopo acidental durante operações autorizadas;
• Execução de binários arbitrários introduzidos no ambiente-alvo.

_ALLOWLIST: Dict[str, Any] = {
    "whoami":   lambda a: ["whoami"],
    "hostname": lambda a: ["hostname"],
    "ls":       lambda a: ["ls", *a],
    "cat":      lambda a: ["cat", *a],
    # ...
}

Nota de segurança: Em produção, argumentos passados para comandos como cat e ls devem ser validados com lógica adicional (e.g., bloqueio de path traversal) dependendo do nível de confiança da sessão.

Reconexão com Exponential Backoff + Jitter

O loop principal implementa reconexão automática com jitter aleatório de ±30% sobre o intervalo base. Isso reduz a previsibilidade do padrão de tráfego de rede, dificultando fingerprinting por IDS/IPS baseados em comportamento temporal.

def _jittered_backoff(backoff: float) -> float:
    jitter = backoff * JITTER_FACTOR * (2 * random.random() - 1)
    return max(1.0, backoff + jitter)

O backoff cresce exponencialmente até MAX_BACKOFF (padrão: 60s), evitando flood em caso de indisponibilidade do servidor.

Autenticação em Tempo Constante

Todas as comparações de credenciais utilizam hmac.compare_digest() ao invés de ==, prevenindo ataques de timing side-channel que poderiam deduzir tokens válidos byte a byte.

---

Configuração

Todas as opções são expostas via variáveis de ambiente. Nenhum segredo é hardcoded.

Variável	Padrão	Descrição
RUNNER_HOST	000.0.0.0	Endereço IP ou hostname do servidor C2
RUNNER_PORT	9000	Porta TCP do servidor
RUNNER_TOKEN	(obrigatório)	Token de autenticação Bearer
RUNNER_HMAC_SECRET	(recomendado)	Segredo para assinatura HMAC-SHA256 das mensagens
RUNNER_CA_CERT	(recomendado)	Caminho para o certificado CA do servidor

Execução

export RUNNER_HOST="192.168.1.100"
export RUNNER_PORT="9000"
export RUNNER_TOKEN="s3cr3t-t0k3n"
export RUNNER_HMAC_SECRET="hmac-secret-key"
export RUNNER_CA_CERT="/path/to/ca.crt"

python c2_agent.py

O agente recusa inicialização se RUNNER_TOKEN não estiver definido, evitando conexões acidentais sem autenticação.

---

Requisitos

• Python 3.8+
• Sem dependências externas — utiliza exclusivamente a biblioteca padrão (ssl, hmac, subprocess, socket, json, uuid)

---

Segurança — Superfície de Ataque e Mitigações

Vetor	Mitigação Implementada	Observação
Interceptação de tráfego	TLS 1.3 obrigatório	Desabilitar verificação de CA apenas em lab
Replay de mensagens	HMAC por mensagem	Não inclui nonce/timestamp; adicionar em produção
Autenticação fraca	hmac.compare_digest	Sem rate limiting no lado agente
Execução arbitrária	Allowlist + shell=False	cat/ls aceitam args; validar em produção
Buffer overflow lógico	MAX_BUFFER_SIZE (1 MB)	Protege contra mensagens malformadas ou gigantes
DoS por timeout	COMMAND_TIMEOUT (20s)	Processos são terminados após o limite

---

Limitações Conhecidas

• Sem nonce/timestamp nas mensagens: o protocolo atual é suscetível a ataques de replay se o canal TLS for comprometido de forma retroativa (e.g., por vazamento da chave privada do servidor no futuro). Mitigação recomendada: incluir campo ts (Unix timestamp) e nonce no envelope e validar no servidor.
• Sem validação de argumentos: comandos como cat e ls repassam argumentos do servidor diretamente ao subprocesso. Em ambientes de alta segurança, adicionar validação de path e listas de argumentos permitidos.
• Persistência não implementada: o agente não instala mecanismos de persistência (cron, systemd, etc.), o que é intencional para manter o escopo do projeto limitado e auditável.

---

Contexto de Uso

Este projeto foi desenvolvido como estudo prático de:

• Implementação de protocolos binários/textuais sobre TLS em Python puro;
• Padrões de autenticação e integridade de mensagens em canais de controle;
• Boas práticas de segurança ofensiva responsável (princípio do menor privilégio, sem hardcode de segredos, logging estruturado);
• Resiliência de conexão em ambientes de rede não confiáveis.

Adequado para uso em laboratórios de red team, CTFs, e ambientes de treinamento em segurança ofensiva com autorização documentada.

---

Licença

Distribuído sob a licença MIT. Veja LICENSE para detalhes.

O uso deste software em sistemas sem autorização prévia e por escrito do proprietário é expressamente proibido.