Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

26 Commits

Folders and files

Repository files navigation

CyberLab

Laboratório local e isolado de pentest/rede para estudo: um exército de máquinas-alvo e uma máquina atacante rodando como containers Docker leves, geridos por uma TUI de terminal (Textual) e por uma CLI.

Feito para treinar red team e testar ferramentas próprias em Python sem peso no PC e sem risco de escapar do lab. Multiplataforma: Linux, Windows e macOS.


O que tem dentro

Componente Descrição
cyberlab-attacker Atacante (debian-slim + nmap, hydra, scapy, paramiko, impacket, vim, nano, neofetch, htop…) com suas ferramentas em /root/tools
cyberlab-webvuln-N Web app vulnerável (SQLi, XSS, LFI, command injection)
cyberlab-shopvuln-N Loja web realista — SQLi, IDOR, SSRF, XSS stored, RCE (médio)
cyberlab-privesc-N Linux com escalação de privilégio (sudo/cron/SUID) — médio
cyberlab-sshweak-N SSH com senhas fracas (brute-force)
cyberlab-ftpanon-N FTP anônimo com arquivos sensíveis
cyberlab-net Rede internal (172.30.0.0/24) — sem rota para a internet

Cada alvo consome poucos MB de RAM; suba quantos quiser.

Topologia

              cyberlab-net 172.30.0.0/24 (internal)
 ┌────────────────────────────────────────────────────┐
 │  attacker (.2)        webvuln-1 (.3)                │
 │                        sshweak-1 (.4)               │
 │                       ftpanon-1 (.5)                │
 └────────────────────────────────────────────────────┘
  [internet = desligado por padrão; toggle liga NAT só no attacker]

Pré-requisitos

  • Docker:
    • Linux: Docker Engine (+ seu usuário no grupo docker).
    • Windows: Docker Desktop (recomendado backend WSL 2). O daemon precisa estar rodando.
  • Python 3.10+.

Instalação

A ferramenta é um pacote Python: instale de qualquer lugar — não precisa clonar nem ter as pastas do projeto. Os Dockerfiles e o exemplo de ferramenta já vão embutidos no pacote.

Linux / macOS

pipx install git+https://github.com/Augustodelf12/CyberLab.py

# sem pipx:
python3 -m venv ~/.cyberlab-venv
~/.cyberlab-venv/bin/pip install git+https://github.com/Augustodelf12/CyberLab.py
~/.cyberlab-venv/bin/cyberlab_py --install   # cria o comando global

Windows (PowerShell)

pip install git+https://github.com/Augustodelf12/CyberLab.py
cyberlab_py --install     # se 'cyberlab_py' não estiver no PATH

--install usa o caminho do Python que está rodando: com o Python do sistema o lançador vai para %APPDATA%\Python\Scripts (e entra no PATH do usuário automaticamente); dentro de um venv, fica nos Scripts do próprio venv (funciona com ele ativado). Para um comando global, prefira pipx ou o Python do sistema.

Primeiro uso

cyberlab_py --setup   # baixa/constrói as imagens (alguns minutos na 1ª vez)

Modo desenvolvimento (clonar)

git clone https://github.com/Augustodelf12/CyberLab.py
cd CyberLab.py
python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/cyberlab_py --setup

Modo web (demonstração do site)

Com CYBERLAB_WEB_MODE=1 (o site oficial define isso ao carregar a versão web), o lab roda reduzido: apenas o atacante e o alvo webvuln podem existir; os demais alvos e os comandos target add, tool add e tool run são recusados com um convite para instalar o app completo. É uma limitação de produto para a demo — fora do modo web nada muda.

Uso (CLI)

cyberlab_py            # abre a TUI / dashboard
cyberlab_py --status   # estado rápido no stdout
cyberlab_py --setup    # rede + imagens faltantes
cyberlab_py --rebuild  # reconstrói todas as imagens
cyberlab_py --nuke     # remove containers e rede do lab
cyberlab_py --install / --uninstall   # comando global no PATH
cyberlab_py --update                  # atualiza o app (sem desinstalar)
cyberlab_py --audit                   # audita o isolamento de rede do lab

Compilar alvos e ferramentas

Qualquer pasta pode virar uma máquina do lab (alvo) ou uma ferramenta:

# === ALVOS (pasta com Dockerfile vira VM-alvo) ===
cyberlab_py target add ./minha-app-vulneravel [--name meu-alvo]
cyberlab_py target list                 # built-in + custom
cyberlab_py target spawn meu-alvo
cyberlab_py target remove meu-alvo

# === FERRAMENTAS (sincronizadas para dentro do atacante) ===
cyberlab_py tool add ./meu-scanner [--name scanner]
cyberlab_py tool list
cyberlab_py tool run scanner 172.30.0.3 1-1024
cyberlab_py tool remove scanner

Entrypoint de ferramenta detectado automaticamente (ordem): main.py → app.py → run.py → tool.py → run.sh/main.sh → executável main. Suas ferramentas/alvos custom ficam em ~/.local/share/cyberlab/ (Linux) ou %LOCALAPPDATA%\CyberLab\ (Windows).

Atalhos da TUI

Tecla Ação
enter (na linha da máquina) abre o terminal dela numa aba
ctrl+n cria novo alvo (menu de tipos)
a importa pasta como alvo ou ferramenta
s liga/desliga a máquina selecionada
x destrói a máquina selecionada (pede confirmação)
i alterna internet (NAT) na máquina atacante
u atualiza o app para a versão mais recente
ctrl+p abre o command palette (importar, atualizar, tema, sair…)
f2 alterna o foco entre terminal e tabela
ctrl+q sai

As abas de terminal têm scrollback (roda do mouse, Shift+setas, Shift+PgUp/PgDn), cores 16/256/24-bit (truecolor), alternate screen (nano/vim/less) e suporte a modo de cursor. Para copiar a saída: arraste com o mouse para selecionar e pressionione Ctrl+C ou Ctrl+Shift+C (sem seleção, copia a linha do cursor). Com texto selecionado, Ctrl+C copia e não interrompe o processo; sem seleção, Ctrl+C segue sendo o interrupção (SIGINT) — o mesmo comportamento do Windows Terminal. Cole com Ctrl+Shift+V.

Terminal embutido no Windows: a TUI e as abas de terminal funcionam nativos — o pseudo-terminal do Windows (ConPTY) entra automaticamente via dependência pywinpty (instalada pelo pip em Windows; no Linux/macOS o app usa ptyprocess). Basta ter o Docker Desktop com o daemon rodando. WSL 2 continua opcional (recomendado pelo desempenho do Docker). Se alguma aba não abrir, gerencie pela TUI e use docker exec -it <máquina> bash por fora — o dashboard segue monitorando.

Treinar / testar suas ferramentas

Suas ferramentas ficam dentro do atacante, em /root/tools:

  1. Crie sua ferramenta em qualquer pasta e registre-a:
    cyberlab_py tool add ./meu-scanner --name scanner
  2. Rode-a direto contra os alvos:
    cyberlab_py tool run scanner 172.30.0.3 1-1024
    ou, na aba do atacante:
    cd /root/tools/scanner && python3 main.py 172.30.0.3 1-1024
  3. Um exemplo portscan.py já vem junto (em /root/tools/portscan.py).

Instalar libs novas no atacante: ligue a internet (tecla i) e rode pip install, ou edite lab/docker/attacker.Dockerfile e rode cyberlab_py --rebuild (mais reprodutível).

Objetivos (flags) de exemplo

Alvo Como Flag
webvuln /search?q=' UNION SELECT flag,2 FROM secrets-- - CYBERLAB{sql1_un10n_xtr4ct}
webvuln /ping?host=127.0.0.1;cat /flag.txt CYBERLAB{w3b_pwn3d_c0ngr4tz}
shopvuln /tools/ping?host=127.0.0.1|cat /flag.txt CYBERLAB{sh0p_rce_m3dium}
privesc sudo find . -exec /bin/sh -p \; -quit depois /root/flag.txt CYBERLAB{pr1v3sc_l1nux}
sshweak hydra contra usuários fracos (root:toor, admin:admin, user:password, backup:backup123) CYBERLAB{ssh_brut3_f0rc3_w1n} em /root/flag.txt
ftpanon login anônimo, baixar pub/flag.txt CYBERLAB{ftp_4n0nym0us_l00t}
shopvuln /search?q=' UNION SELECT username,password FROM users-- - → login → RCE em /tools/ping CYBERLAB{sh0p_rce_m3dium}
privesc SSH como dev:dev123 → sudo -l/cron/SUID → root CYBERLAB{pr1v3sc_l1nux}

Writeups completos de todos os labs: consulte a pasta docs/.

Segurança

  • A rede é internal: true: os alvos não têm internet e nenhuma porta é publicada no host. Todo o tráfego fica em cyberlab-net.
  • O attacker nasce sem internet; ganha NAT só se você ativar (tecla i).
  • Nunca altere os Dockerfiles para publicar portas ou remover o internal — aí o lab deixa de ser isolado e expõe máquinas vulneráveis na LAN.

Modo airgap (uso crítico)

Para garantir zero conexão de rede externa — ideal para pentest de código crítico/sensível — rode com CYBERLAB_AIRGAP=1:

CYBERLAB_AIRGAP=1 cyberlab_py --setup
CYBERLAB_AIRGAP=1 cyberlab_py            # TUI com internet travada

Nesse modo o toggle de internet é desabilitado (o botão fica "travada"), --update é bloqueado e, se qualquer máquina do lab ainda estava ligada a uma rede externa (ex.: atacante na bridge/NAT) antes de ativar o airgap, a desconexão é forçada no próximo --setup/--audit/abertura da TUI.

--audit nunca "afrouxa" o relatório no airgap: ele lê o estado real da rede no Docker. Audite a qualquer momento:

cyberlab_py --audit

que verifica: rede interna, ausência de portas publicadas no host, atacante sem NAT e containers restritos à rede do lab.

Fronteiras de confiança (o que é "seguro por desenho")

  • cyberlab_py target add <pasta> roda docker build no código da pasta: um build roda com privilégio do daemon Docker — só importe Dockerfiles em que você mesmo confiaria para executar. Mesmo contrato de docker build.
  • cyberlab_py tool add copia para ~/.local/share/cyberlab/tools e monta em /root/tools do atacante (leitura/escrita). Ferramentas adicionadas rodam como root dentro do atacante: só adicione código seu.
  • Atenção ao volume rw: um atacante comprometido (ex.: ferramenta importada de terceiros, writeup malicioso, listener explorado) pode gravar arquivos no seu home (dentro de tools/) como root do container — sem userns-remap esses arquivos aparecem como root:root no host. Nunca execute código de tools/ fora do lab (no host), e desconfie de arquivos que você não criou lá. Para matar essa via por completo, ative userns-remap no daemon ou mude o mount para ro.
  • Registry de alvos/ferramentas em JSON — o app valida literalmente que a pasta de destino está dentro de tools/ antes de apagar algo, ignora nomes reservados (attacker) e rejeita nomes de travessia (..).
  • O laboratório não usa docker socket em nenhum container, nem monta /proc//sys, nem publica porta no host.
  • Limites de recursos: alvos nascem com mem_limit + pids_limit=256 e o atacante com pids_limit=512 — um fork bomb dentro do lab não exaure os PIDs do host.
  • --update reinstala a partir de git+https://… (branch default, sem verificação de integridade além do TLS). O mecanismo tem a mesma confiança de um pip install manual: um repositório upstream comprometido compromete o host. CYBERLAB_UPDATE_URL sobrescreve a fonte — trate essa env como código confiável.

Estrutura

CyberLab.py/
├── pyproject.toml            # empacotamento (deps por plataforma: ptyprocess/pywinpty)
├── main.py                   # shim p/ rodar da fonte (dev)
├── requirements.txt
├── .gitignore
├── lab/
│   ├── cli.py                # CLI (target/tool/setup/install…)
│   ├── manager.py            # Docker SDK: rede, containers, métricas, registry
│   ├── terminal.py           # widget Terminal (PTY portátil + pyte + scrollback)
│   ├── paths.py              # assets embutidos + data dir do usuário
│   ├── app.py                # TUI (Textual)
│   ├── docker/               # Dockerfiles do atacante e dos alvos (package data)
│   └── examples/             # ferramentas de exemplo
├── docs/                     # writeups de hacking de todos os labs
├── site/                     # landing page de divulgação (HTML/CSS)
└── tests/                    # testes: segurança, Windows-compat, modo web (CI)
                              #        + fumaça com Docker real (manager/TUI/terminal)

Rodar os testes (desenvolvimento)

Sem Docker (rodam em qualquer máquina/CI):

python tests/test_security.py         # regressões de segurança (airgap, registry, slug…)
python tests/test_windows_compat.py  # portabilidade Windows + instalador (mocks)
python tests/test_web_mode.py        # bloqueios do modo web do site
python tests/test_terminal_features.py  # widget Terminal sem TUI (cores, resize, PTY real)

Com Docker rodando (fumaça de ponta a ponta):

python tests/test_manager.py         # cria/destrói alvos de verdade
python tests/test_tui.py             # TUI headless (modo run_test)
python tests/test_terminal.py        # terminal embutido + scrollback no atacante
python tests/test_custom.py          # alvos/ferramentas custom

Ou tudo de uma vez com pytest tests/.

Problemas comuns

  • docker indisponível: inicie o daemon (sudo systemctl start docker no Linux; abra o Docker Desktop no Windows) e garanta estar no grupo docker.
  • cyberlab_py não é reconhecido: instale com pipx (Linux) ou rode cyberlab_py --install para criar o launcher global; feche e reabra o terminal.
  • VS Code (Flatpak) no Linux: o terminal embutido do editor é um sandbox; rode a TUI no terminal do sistema para acessar o Docker do host.
  • Terminal embutido não abre (Windows): instale o backend de PTY (pip install pywinpty) ou verifique se o Docker Desktop está rodando; alternativamente docker exec -it <máquina> bash por fora.
  • Lentidão no primeiro uso: é o build das imagens (--setup); depois os containers sobem em segundos.

Changelog

v1.1.5a0 — Windows nativo de ponta a ponta

  • Terminais embutidos nativos no Windows via ConPTY (pywinpty): o backend de PTY agora é selecionado por plataforma (Linux/macOS usam ptyprocess, Windows usa pywinpty) — instalar e usar, sem WSL2.
  • CLI e TUI rodando em qualquer SO: fcntl/PTY deixou de ser requisito de importação; sem backend disponível, a TUI avisa e segue gerenciável.
  • Instalador do comando global corrigido: caminho derivado do Python em uso (sistema x venv), criação verificada antes de anunciar sucesso, idempotente, e o PATH do usuário é preservado (sem setx).
  • Modo web do site (CYBERLAB_WEB_MODE=1): lab reduzido para a demo (atacante + webvuln), com convite para instalar o app completo.
  • Testes novos: test_windows_compat.py (42 verificações sem Docker) e PTY real no test_terminal_features.py.

Auditoria de segurança (AppSec) — hardening da plataforma

  • tool add --name .. destruiria o diretório de dados: nomes de travessia (./..) e o nome reservado attacker são rejeitados (CWE-22).
  • Sync de exemplos não segue mais symlinks plantados no volume (CWE-59); containers nascem com pids_limit (anti fork-bomb no host, CWE-400).
  • Airgap sem vias secundárias: enforce_airgap desconecta qualquer container do lab de qualquer rede externa; --audit lê o estado real.
  • Registry com lock + escrita atômica; remove_tool valida o caminho antes de apagar; bind mount comparado por caminho resolvido.
  • Terminal: resize sob lock (pyte não é thread-safe) e painel encerrado não vaza teclas para as ações globais da TUI.

v1.1.1 — site de divulgação + alvos médios

  • Alvos shopvuln (SQLi, IDOR, SSRF, XSS stored, RCE) e privesc (sudo/cron), writeups em docs/.

v1.0.5 — modo airgap e auditoria de rede

  • CYBERLAB_AIRGAP=1, --audit (rede internal, portas, NAT, containers), sparklines em tempo real e atualização do app pela TUI.

Histórico completo: git log --oneline.


Site do projeto

Acesse a página oficial — documentação, alvos, arquitetura e instalação em um só lugar:

CyberLab

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages