Dominando a Documentação

A necessidade mais comum que você terá de consultar a documentação é simplesmente descobrir como usar a infinidade de programas disponíveis — e, em particular, descobrir quais argumentos passar na linha de comando. Este módulo focará amplamente nesse conceito como base para entender o funcionamento geral de programas. Ao longo do módulo, exploraremos diversas formas de solicitar ajuda ao sistema, mas primeiro vamos exercitar a leitura direta da documentação.

O uso correto dos programas depende, em grande parte, de fornecer os argumentos adequados. Lembre-se do modificador -a em ls -a no desafio de arquivos ocultos do módulo Compreendendo Comandos: aquele -a foi um argumento que instruiu o ls a listar tanto arquivos ocultos quanto não ocultos. Como o nosso objetivo era listar arquivos ocultos, invocar ls com o argumento -a foi a escolha precisa para aquele cenário.

O programa deste desafio é /challenge/challenge, e você precisará invocá-lo corretamente para que ele entregue a flag. Imagine que a documentação dele seja a seguinte:

Bem-vindo à documentação do /challenge/challenge! Para executar este programa corretamente, você deve passar a ele o argumento --giveflag. Boa sorte!

Com base nessa informação, vá em frente e capture a flag!

Embora a maioria dos comandos seja simples de usar, a sintaxe de alguns utilitários pode ser bastante sofisticada. Por exemplo, os argumentos passados para ferramentas como sed e awk (que não abordaremos no momento) são praticamente programas inteiros escritos em linguagens próprias! Em algum ponto no espectro entre o simples cd e o complexo awk, existem comandos que recebem argumentos para os seus próprios argumentos...

Isso pode soar estranho no início, mas você já presenciou isso no nível do find em Compreendendo Comandos. O find aceita o argumento -name, e a opção -name, por sua vez, exige um argumento próprio indicando o padrão de nome a ser buscado. Muitos outros comandos funcionam de maneira análoga.

Veja a documentação deste nível para /challenge/challenge:

Bem-vindo à documentação do /challenge/challenge! Este programa exibe o conteúdo de arquivos arbitrários no terminal quando recebe o argumento --printfile. O argumento para --printfile é o caminho do arquivo a ser lido. Por exemplo, /challenge/challenge --printfile /etc/hostname exibirá o hostname do container!

Com base nessa documentação, vá e capture a flag!

Este nível apresenta o comando man. man é uma abreviação de manual, e exibe (quando disponível) o manual de instruções do comando passado como argumento. Por exemplo, imagine que queiramos aprender sobre o comando yes (sim, este é um comando real do Linux):

hacker@dojo:~$ man yes

Isso exibirá a página de manual (man page) do yes, parecida com isto:

YES(1)                           User Commands                          YES(1)

NAME
       yes - output a string repeatedly until killed

SYNOPSIS
       yes [STRING]...
       yes OPTION

DESCRIPTION
       Repeatedly output a line with all specified STRING(s), or 'y'.

       --help display this help and exit

       --version
              output version information and exit

AUTHOR
       Written by David MacKenzie.

REPORTING BUGS
       GNU coreutils online help: <https://www.gnu.org/software/coreutils/>
       Report any translation bugs to <https://translationproject.org/team/>

COPYRIGHT
       Copyright  ©  2020  Free Software Foundation, Inc.  License GPLv3+: GNU
       GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
       This is free software: you are free  to  change  and  redistribute  it.
       There is NO WARRANTY, to the extent permitted by law.

SEE ALSO
       Full documentation <https://www.gnu.org/software/coreutils/yes>
       or available locally via: info '(coreutils) yes invocation'

GNU coreutils 8.32               February 2022                          YES(1)

As seções mais importantes de uma manpage são:

NOME(1)                           CATEGORIA                         NOME(1)

NAME (NOME)
	Informa o nome e uma breve descrição do comando ou conceito
	abordado na página.

SYNOPSIS (SINOPSE)
	Apresenta uma sinopse resumida da sintaxe de uso. Essas sinopses
	seguem um formato padrão. Tipicamente, cada linha é uma invocação
	válida do comando, podendo ser interpretada como:

	COMANDO [ARGUMENTO_OPCIONAL] ARGUMENTO_OBRIGATORIO_UNICO
	COMANDO [ARGUMENTO_OPCIONAL] MULTIPLOS_ARGUMENTOS...

DESCRIPTION (DESCRIÇÃO)
	Detalhamento completo do comando ou conceito, com descrições
	minuciosas de cada uma das opções disponíveis.

SEE ALSO (VEJA TAMBÉM)
	Outras páginas de manual ou recursos online que podem ser úteis.

COLEÇÃO                           DATA                              NOME(1)

Você pode navegar pela manpage usando as setas do teclado (↑ / ↓) e as teclas PgUp / PgDn. Quando terminar de ler o manual, pressione q para sair e voltar ao terminal.

As páginas man ficam armazenadas em uma base de dados centralizada do sistema. Por curiosidade, essa base reside no diretório /usr/share/man, mas você nunca precisará acessá-la diretamente: basta consultá-la usando o comando man. Os argumentos passados ao man não são caminhos de arquivos, mas apenas os nomes das entradas (por exemplo, execute man yes para consultar o manual do yes, em vez de man /usr/bin/yes, que é o caminho real do executável mas faria o man falhar ou exibir caracteres ilegíveis).

O desafio deste nível possui uma opção secreta que, quando informada, fará o programa imprimir a flag. Você deve descobrir qual é essa opção lendo a página de manual do challenge!

Você pode rolar as páginas do manual com as teclas de seta (e PgUp / PgDn) e realizar buscas digitando /. Após iniciar a busca pelo termo desejado, pressione n para avançar até o próximo resultado e N (Shift + n) para retornar ao resultado anterior. Em vez de /, você também pode utilizar ? para pesquisar no sentido inverso (de baixo para cima)!

Encontre a opção que revelará a flag lendo atentamente a man page do comando challenge.

Este nível é engenhoso: a página de manual do desafio foi escondida com um nome aleatório. Felizmente, todas as páginas man são reunidas em uma base de dados pesquisável, o que permite buscar no catálogo do sistema até encontrar a man page oculta do desafio! Para aprender como pesquisar pela página de manual correta, consulte a própria manpage do comando man executando: man man!

DICA 1: man man ensina o uso avançado do próprio utilitário man, e você deverá usar esse conhecimento para descobrir como pesquisar pela manpage escondida que ensinará a usar /challenge/challenge.

DICA 2: Embora a página de manual tenha um nome aleatório, o executável que você chamará para obter a flag continua sendo /challenge/challenge!

Alguns programas não possuem uma página de manual formal, mas ensinam como usá-los quando invocados com um argumento especial de ajuda. Normalmente, esse argumento é --help, mas muitas vezes pode ser -h ou, em casos mais raros, -?, help, ou formatos esotéricos como /? (embora este último seja mais comum no Windows).

Neste nível, você praticará a consulta da documentação de um programa utilizando --help. Experimente agora mesmo!

Certos comandos, em vez de serem programas externos com páginas man e opções de ajuda próprias, são embutidos diretamente na própria shell. Eles são chamados de comandos internos ou builtins. Os builtins são executados exatamente como qualquer outro comando, mas a shell os processa internamente em vez de lançar um novo programa no sistema. Você pode obter uma lista completa dos comandos builtins da shell executando o builtin help, desta forma:

hacker@dojo:~$ help

Você pode obter ajuda sobre um comando específico passando-o como argumento para o builtin help. Vejamos a documentação de um comando interno que já utilizamos antes, o cd!

hacker@dojo:~$ help cd
cd: cd [-L|[-P [-e]] [-@]] [dir]
    Change the shell working directory.
    
    Change the current directory to DIR.  The default DIR is the value of the
    HOME shell variable.
...

Excelente informação! Neste desafio, praticaremos o uso do help para consultar a documentação de comandos builtins. O comando challenge deste nível é um comando interno da shell (builtin), e não um arquivo executável isolado. Como antes, você precisará consultar a sua ajuda para descobrir o valor secreto que deve ser passado a ele!