jrice-ai/cageHarness de reprodução, patches e ferramentas de análise para auditar um benchmark de ciberdefesa baseado em aprendizado: captura traces de agentes, executa ablações de agentes vermelhos e recalcula cada figura do artigo a partir dos dados divulgados.
Este repositório é o harness, os patches, as ferramentas de análise e o ledger por trás do artigo What a CAGE 4 Score Measures: An Audit of a Learned Cyber-Defense Benchmark, Its Reference Defenders, and the Tables Built on Them (James M. Rice e orientadores, Rochester Institute of Technology, 2026). O identificador arXiv é adicionado aqui no primeiro commit após a publicação. A tag arxiv-v1 é o estado a partir do qual cada número do artigo publicado foi calculado.
Os traces e checkpoints a partir dos quais os números do artigo são calculados estão depositados separadamente, em https://doi.org/10.5281/zenodo.23681828, em quatro arquivos.
| Arquivo | Conteúdo | Descompactar em | sha256 |
|---|---|---|---|
traces_arms_arxiv-v1.tar.zst | os registros de passos de cada braço de avaliação da auditoria principal, os 123 que o Apêndice B do artigo lista e os braços de diagnóstico que ARMS.md nomeia, um diretório por braço, um arquivo JSON-lines por episódio | data/traces/ | db2c3d17684180e5d4ca7fb9a7f1f739b5414e62da0e8c4b9b792cd31568f456 |
traces_pilot_arxiv-v1.tar.zst | os registros de passos do piloto de verificação de ocupação e sua continuação (braços nomeados kbf_*) | data/traces/ | ece72ca24d17bf688144b2d0276ae9f0209aa8a50f95ecdd0aab9a6f8a9c0fc0 |
checkpoints_pilot_arxiv-v1.tar.zst | os checkpoints mantidos e o estado de retomada das execuções de treinamento do piloto e da continuação | repos/cage-4-submission/checkpoints/ | dc2c8219e12a0c2931263be0003c8858039931b04b019e1bfa60c0ba6856c07e |
checkpoints_continuation_arxiv-v1.tar.zst | os checkpoints das execuções de continuação do Wrecker da Seção 5 | repos/cage-4-submission/checkpoints/ | em SHA256SUMS |
run_logs_arxiv-v1.tar.zst | os logs de treinamento e avaliação das execuções do piloto e da continuação de ambas as máquinas, com pilot_runs.log, que registra o host, a contagem de threads, a contagem de workers, o digest do código e a imagem de cada execução | data/ | em SHA256SUMS |
O SHA256SUMS no depósito lista todos os quatro. Verifique um arquivo com sha256sum -c SHA256SUMS antes de descompactar.
| Caminho | O que é |
|---|---|
bin/run | executa um comando em uma das duas imagens com este diretório montado em /work, repassando os interruptores KEEP_* e HMARL_*. Ele espera o clone em ~/cage. |
build/ | os dois Dockerfiles (Dockerfile.keep, Dockerfile.marl) e os patches aplicados aos repositórios upstream antes da construção das imagens |
scripts/capture.py | executa a política liberada do KEEP em seeds de ambiente pareadas e grava o registro de passos com as observações brutas dos agentes e o estado verdadeiro do simulador |
scripts/capture_hmarl.py | o mesmo para o H-MARL Expert, pelo caminho de avaliação dos autores (--compat) ou pelo harness supervisório |
scripts/oracle.py, scripts/oracle_rules.py | o harness supervisório no KEEP, as regras O1 a O15 e os defensores de regras, com os interruptores de entrega (--wait-busy, --queue, --min-gap) |
red_agents/ | os adversários que o artigo executa além do FiniteStateRedAgent padrão. Wrecker e suas escadas Pn e Qn são do próprio artigo (Seção 2), e bin/run copia todos os arquivos daqui para o diretório SimpleAgents da imagem no lançamento |
tools_*.py | as ferramentas de análise. tools_paired.py (diferença pareada, intervalo bootstrap, vitórias, teste de sinal), tools_charge.py e tools_busy_charge.py (a carga de Restore e o restante), tools_dropped.py (executado contra intervenções asseveradas), tools_cont.py, tools_ceiling.py, tools_fraction_ci.py, tools_latch_sum.py, tools_drawspread.py, tools_lagcorr.py, tools_busy_restores.py, tools_pilot_decisions.py e o restante. Cada um imprime o que calcula a partir de um diretório de traces em data/traces/ |
tools_patch_*.py | a pilha de patches sobre o código liberado. tools_patch_keep_busy.py, tools_patch_keep_seedmode.py e tools_patch_keep_readall.py, nessa ordem, dão ao treinador do KEEP os interruptores da Seção 6. tools_patch_hmarl_busy.py dá ao wrapper do H-MARL o interruptor HMARL_BUSY=none. tools_patch_oracle_truth.py adiciona --log-truth ao harness. Cada um é idempotente e se recusa a rodar em código que não reconhece |
run_keep_pilot.sh, eval_keep_pilot.sh, pilot_status.sh, test_keep_*.sh | o piloto e a continuação da Seção 6, sua avaliação e seus testes |
run_busy_reds.sh | a política liberada do KEEP com sua verificação de ocupado ligada e desligada no adversário padrão e em nove outros (Seção 6.1) |
queue_*.sh, read_*.sh, run_*.sh, rerun_F.sh, gate_O15.sh, pilot_O15.sh, svy_O15.sh | os lançadores e leitores da campanha. Cada braço do artigo foi lançado por um destes, então eles são o registro da invocação exata de cada braço |
ARMS.md | cada braço, por nome, com seu comando, sua média e o arquivo que a contém |
RESULTS.md | o log datado do trabalho, mais recente primeiro |
papers/ | a cópia do artefato da camada de análise do artigo, sem o texto do artigo. papers/paper1/ledger.csv é o ledger, uma linha por número impresso no artigo, com o comando que o recalcula. papers/paper1/fig/ contém os scripts de figuras e tabelas. papers/paper1/check_identities.py testa as identidades aritméticas que toda build deve satisfazer. Os scripts recompute_*.py e means.py em papers/ são os cálculos de critério, variância e participação que o ledger chama |
Tudo em data/ e repos/ é ignorado pelo git. Os traces vão para data/traces/, os repositórios upstream e os checkpoints para repos/.
O Apêndice A do artigo nomeia três níveis. Eles precisam de cada vez mais do ambiente.
Clone, descompacte os dois arquivos de traces em data/traces/ e execute o recálculo a partir da raiz do repositório. Ele executa cada comando distinto do ledger a partir deste diretório e verifica se o valor armazenado de cada linha aparece na saída desse comando.
git clone https://github.com/jrice-ai/cage ~/cage && cd ~/cage && git checkout arxiv-v1
mkdir -p data/traces && tar -I zstd -xf traces_arms_arxiv-v1.tar.zst -C data/traces && tar -I zstd -xf traces_pilot_arxiv-v1.tar.zst -C data/traces
./recompute.sh
python3 papers/paper1/check_identities.py papers/paper1/ledger.csv
Os comandos do ledger nomeiam a camada de análise pelo seu caminho na máquina dos autores, ~/papers, então recompute.sh executa a verificação com HOME apontado para um diretório temporário que vincula papers/ ali. Nada é escrito fora do repositório. Em um laptop, a recomputação completa leva dezenas de minutos, a maior parte nas execuções piloto. Dez linhas, os hiperparâmetros lidos dos checkpoints publicados (chaves keep* e trident*, que executam via bin/run), precisam da imagem de nível 2 e são reportadas como não encontradas sem ela. check_identities.py reporta as identidades aritméticas (custo é igual a cobrança mais resto para cada split, os intervalos de quatro sorteios e quatro sementes contra suas médias e desvios padrão, o resto zero do par H-MARL com máscara desativada). Os scripts de figuras e tabelas em papers/paper1/fig/ regeneram as figuras e tabelas do artigo a partir dos mesmos traces com CAGE=~/cage python3 papers/paper1/fig/fig_curves.py e da mesma forma para fig_drop.py, fig_noise.py, make_tables.py, make_busyreds.py e make_arms.py.
Isto requer as duas imagens, os repositórios upstream em suas revisões fixadas e os checkpoints publicados.
Clone os três repositórios upstream em repos/ nas revisões a partir das quais o artigo foi calculado, que são as revisões impressas na Tabela 12 do artigo.