Przejdź do głównej zawartości

TrapCLI

TrapCLI to pomocnicza aplikacja, która znajduje się w każdej pułapce. Obsługuje ona komunikacje pułapki z panelem TrapInit - zajmuje się m. in. wysyłaniem powiadomień czy obsługą sprawdzania statusu pułapki.

Autor pułapki powinien upewnić się, że TrapCLI jest poprawnie dodawany do obrazu pułapki, i używać wyłącznie TrapCLI do komunikacji z TrapInit.

Pobieranie​

TrapCLI można pobrać z downloads.traptech.pl. Dostępna jest dla systemu Windows, oraz Linux (w wersji dla systemów z glibc i musl).

Aplikację można pobierać za pomocą curl, używając następujących adresów:

  • Windows: https://downloads.traptech.pl/data/TrapCLI-v<wersja>.exe

  • Linux z glibc: https://downloads.traptech.pl/data/TrapCLI-v<wersja>

  • Linux z musl: https://downloads.traptech.pl/data/TrapCLI-musl-v<wersja>

<wersja> należy zastąpić aktualną wersją TrapCLI - np. 1.2.2.

Przykłady Dockerfile​

Poniższe przykłady Dockerfile generują obraz zawierający TrapCLI w PATH.

FROM curlimages/curl as trapcli

# Download and install TrapCLI
ARG TRAPCLI_VERSION=1.2.2
RUN curl -f https://downloads.traptech.pl/data/TrapCLI-v${TRAPCLI_VERSION} -o /home/curl_user/TrapCLI \
    && chmod +x /home/curl_user/TrapCLI

FROM ubuntu

COPY --from=trapcli /home/curl_user/TrapCLI /usr/bin/TrapCLI

Dodatkowe zależności​

Na systemie Windows nie powinna być wymagana instalacja żadnych dodatkowych zależności.

Większość dystrybucji korzystających z Linux'a z glibc (m. in. Ubuntu) powinno również działać bez dodatkowych pakietów. W razie problemów należy upewnić się, że na systemie znajdują się pakiety ca-certificates, zlib i libstdc++ (lub ich odpowiedniki, w zależności od dystrybucji).

Na systemach Linux z musl (takich jak Alpine) może być wymagane doinstalowanie dodatkowych pakietów - ca-certificates, zlib, libgcc i libstdc++.

W przypadku obrazów bazujących na Alpine, następująca linijka w Dockerfile instaluje te pakiety:

RUN apk add ca-certificates zlib libgcc libstdc++

Korzystanie z narzędzia​

TrapCLI do działania wymaga odpowiedniej konfiguracji, którą odczytuje z następujących zmiennych środowiskowych:

  • TRAP_LOG_ENDPOINT

  • TRAP_LOG_TOKEN

  • TRAPCLI_DISABLE_SSL_VALIDATION

Te zmienne środowiskowe są automatyczne ustawiane przez TrapInit w czasie tworzenia pułapki. Należy tylko pamiętać o przekazaniu ich do kontenera zawierającego TrapCLI.

Wykonujemy to w docker-compose.yml w taki sposób:

container_with_trapcli:
  image: my-image
  environment:
    - TRAP_LOG_ENDPOINT
    - TRAP_LOG_TOKEN
    - TRAPCLI_DISABLE_SSL_VALIDATION

Główne funkcjonalności TrapCLI zawierają się w dwóch podkomendach daemon i send-incident. Dokładny opis każdej komendy i dostępnych argumentów możemy uzyskać wywołując TrapCLI z flagą --help:

$ TrapCLI --help
Description:
  CLI used to communicate with TrapInit instance
      to send incident and system logs

Usage:
  TrapCLI [command] [options]

Options:
  --version       Show version information
  -?, -h, --help  Show help and usage information

Commands:
  daemon         Starts the CLI in daemon mode. Performs several function related to reporting trap status
  send-incident  Sends an incident notification to the TrapInit app.

daemon​

daemon uruchamia TrapCLI w trybie daemon (serwisu). W tym trybie TrapCLI cały czas działa, i wykonuje kilka niezbędnych do poprawnego działania pułapki operacji, m. in. zbiera i wysyła informacje potrzebne do funkcjonalności inwestygacji, czy wysyła wiadomość ping, potwierdzającą w panelu TrapInit że komunikacja z pułapką działa poprawnie.

W związku z tym w każdej pułapce przynajmniej jeden kontener musi uruchamiać podczas startu TrapCLI daemon. Zwykle powinien być to główny kontener pułapki, w którym zawiera się główna logika aplikacji.

Możemy uruchomić TrapCLI daemon jako proces w tle, dzięki czemu jednocześnie możemy w kontenerze uruchomić główny proces aplikacji. Możemy to zrobić jak w poniższym przykładzie:

# Upewnij się że TrapCLI jest pobrane i dostępne w kontenerze!
# & oznacza uruchomienie poprzedzającej komendy w tle
# Zakładamy że app.sh uruchamia proces aplikacji, może to być dowolna inna komenda
CMD TrapCLI daemon & ./app.sh

send-incident​

send-incident to komenda służąca do wysyłania incydentu do panelu TrapInit. Pułapka powinna ją wywoływać kiedy potrzebne jest wysłanie incydentu. W większości języków programowania można wywołać dowolną komendę w systemie - np. w Python za pomocą subprocess.run czy w Node za pomocą child_process.exec.

Do poprawnego wywołania komendy wymagane jest podanie nazwy incydentu (--name), poziomu (--severity) i IP klienta który wywołał incident (--source-ip).

$ TrapCLI send-incident --help
Description:
  Sends an incident notification to the TrapInit app.

Usage:
  TrapCLI send-incident [options]

Options:
  -n, --name <name> (REQUIRED)                                 Name of the created incident
  -d, --description <description>                              Description of the created incident
  -s, --severity <Attempt|Ignored|Incident|Info> (REQUIRED)    Severity of the created incident
  -i, --ip, --source-ip <source-ip> (REQUIRED)                 Source IP of the connection that triggered the incident
  -b, --bait-dynamic-value, --bait-value <bait-dynamic-value>  Dynamic value used to inform which bait triggered the incident
  -c, --custom-data <custom-data>                              Custom data to show about the incident
  -?, -h, --help                                               Show help and usage information