README.md

Host Patrol

_{Lazy Hacker's Linux Host Patrol}

Host Patrol (hostpatrol) is a command-line application to retrieve information from remote hosts. The information is retrieved over SSH by executing small scripts. Then, the information is compiled into JSON to be further analysed or visualised on its Website.

The report contains following information for each host:

1. Hardware resources: (v)CPU count, total RAM, root filesystem disk size
2. Kernel information
3. Linux distribution information as in os-release
4. List of all Docker containers (in all states)
5. List of systemd services
6. List of systemd timers
7. List of authorised SSH public keys found on the host
8. Cloud information: (if any)
   • Cloud provider name
   • Host instance identifier
   • Host type
   • Region
   • Availability zone
   • Local hostname
   • Local address
   • Remote hostname
   • Remote address
   • Reserved address

Installation

Currently, the easiest way to install the command-line application is via Nix:

nix profile install --file https://github.com/vst/hostpatrol/archive/v<VERSION>.tar.gz app

Alternatively, you can use the statically compiled binary distributed along with each release (Linux x86_64 only).

Usage

hostpatrol assumes that you are able to connect to remote hosts via SSH:

ssh my-host

Indeed, hostpatrol uses ssh under the hood. Therefore, if you can ssh, you can hostpatrol!

Note

If you are using SSH public key authentication to connect to host and your SSH private key is password-protected, use SSH-agent and unlock your private key first.

You can pass hosts via CLI arguments:

hostpatrol compile --host my-host-1 --host my-host-2 > /tmp/hostpatrol-report.json

This command connects to hosts in parallel and ignores all failed hosts by reporting errors in the output.

If you want to change the number of maximum number of threads to use for concurrent patrol tasks, do so with --threads option that defaults to 4 otherwise:

hostpatrol compile --threads 10 --host my-host-1 --host my-host-2 ... > /tmp/hostpatrol-report.json

Alternatively, you can use a configuration file which has additional benefit of attaching static information to your hosts such as external documentation URL and/or tags, and using SSH configuration instead of plain host name. The configuration file looks like as follows:

## config.yaml
## List of known SSH public keys for all hosts.
knownSshKeys:
  - gh:some-github-user
  - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKq9bpy0IIfDnlgaTCQk0YhKyKFqInRjoqeIPlBuiFwS test-key-admin

## List of hosts to patrol
hosts:
  - ## Name of the host (required)
    name: somehost
    ## SSH configuration (optional)
    ssh:
      ## SSH destination (required)
      destination: [email protected]
      ## SSH options (optional)
      options: ["-i", "/keys/hebele.pri"]
    ## External identifier of the host (optional)
    id: 20b88669-743f-4ae5-9823-5aacc2df7086
    ## External URL for the host (optional)
    url: https://internal.documentation/hosts/somehost
    ## List of tags for the host (optional)
    tags:
      - oranges
      - strawberries
    ## Arbitrary JSON data for the host (optional)
    data:
      owner: Client-1
      cost: 50
    ## List of known SSH public keys for the host (optional)
    knownSshKeys:
      - gh:another-github-user
      - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGmlBxUagOqtWcW6B77TUL8li85ZNYx0tphd3TSx4SEB test-key-tenant
  - name: otherhost
    url: https://internal.documentation/hosts/otherhost
    tags:
      - apples
      - strawberries

Then, you can use this configuration file instead of specifying hosts individually on the command-line:

hostpatrol compile --config config.yaml > /tmp/hostpatrol-report.json

..., or mix with --host option:

hostpatrol compile --config config.yaml --host a-host --host b-host > /tmp/hostpatrol-report.json

Users can process/analyse the JSON output themselves or use Website to list, tabulate and visualise the information.

Note

The Website stores the report locally in the Web browser using local storage. It is not sent to any third party service. You can study the Website source-code that is automatically published to GitHub Pages.

Development

The codebase comes with a Nix shell. You can use direnv for convenience:

direnv allow

Big, long format, lint, build and test command for the impatient:

hpack &&
    direnv reload &&
    fourmolu -i app/ src/ test/ &&
    prettier --write . &&
    find . -iname "*.nix" -not -path "*/nix/sources.nix" -and -not -path "*/website/node_modules/*.nix" -print0 | xargs --null nixpkgs-fmt &&
    hlint app/ src/ test/ &&
    cabal build -O0 &&
    cabal run -O0 hostpatrol -- --version &&
    cabal v1-test &&
    cabal haddock -O0

For testing and building:

dev-test-build

License

Copyright © 2024 Vehbi Sinan Tunalioglu. This work is licensed under MIT License.