Skip to main content
Version: 19.x (unreleased)

Configure SSH with the Linux Auditing System

Report an IssueView as Markdown

You can configure Teleport's SSH Service to integrate with the Linux Auditing System (auditd).

Prerequisites​

  • A running Teleport cluster. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

  • The tctl and tsh clients.

    Installing tctl and tsh clients

    1. Determine the version of your Teleport cluster. The tctl and tsh clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at /v1/webapi/find and use a JSON query tool to obtain your cluster version. Replace teleport.example.com:443 with the web address of your Teleport Proxy Service:

      TELEPORT_DOMAIN=teleport.example.com:443
      TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"

    2. Follow the instructions for your platform to install tctl and tsh clients:

      Download the signed macOS .pkg installer for Teleport, which includes the tctl and tsh clients:

      curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg

      In Finder double-click the pkg file to begin installation.

      danger

      Using Homebrew to install Teleport is not supported. The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security.

  • A running Teleport Agent instance. See the getting started guide for how to add an agent to your Teleport cluster. On the agent, teleport must be running as a systemd service with root permissions.
  • Linux kernel 2.6.6+ compiled with CONFIG_AUDIT. Most Linux distributions have this option enabled by default.
  • auditctl to check auditd status (optional).
  • To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands using your current credentials. For example, run the following command, assigning teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and [email protected] to your Teleport username: 
    tsh login --proxy=teleport.example.com --user=[email protected]
    tctl status
    Cluster  teleport.example.com
    Version  19.0.0-dev
    CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
    If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.

Step 1/3. Check system configuration​

Teleport automatically sends auditd events when it discovers that auditd is enabled in the system. You can verify that by calling auditctl -s as root.

Here is an example output from that command:

sudo auditctl -s
enabled 1failure 1pid 879rate_limit 0backlog_limit 8192lost 0backlog 0backlog_wait_time 60000backlog_wait_time_actual 0loginuid_immutable 0 unlocked

The first line enabled 1 indicates that auditd is enabled, and Teleport will send events.

All events are generated on a Teleport Node. invalid user events are also generated on the Proxy Service when a Teleport user fails to authenticate.

Step 2/3. Configure and start Teleport​

It's important to run Teleport as a system service (systemd service, for example) with root permissions. Otherwise, Teleport won't send any events to auditd due to lack of permissions.

  1. [Optional] Auditd can generate additional events when PAM (Pluggable Authentication Modules) is enabled.

    To enable the PAM integration in Teleport, add the following pam section to the configuration file on your Teleport Node (/etc/teleport.yaml by default):

    ssh_service:
  # Enabled SSH Service
  enabled: true
  # Enable PAM integration
  pam:
    # "no" by default
    enabled: true
    # use /etc/pam.d/sshd configuration (the default)
    service_name: "sshd"

    PAM-generated events depend on your sshd configuration when the integration is enabled. Most systems generate events like USER_ACCT or USER_START. Additionally, TTY input can be logged by enabling the pam_tty_audit.so module.

    For more details please refer to PAM or your operating system documentation.

    When PAM integration is enabled, auditd events should closely match events generated by OpenSSH.

  2. Configure your Teleport instance to start automatically when the host boots up by creating a systemd service for it. The instructions depend on how you installed your Teleport instance.

    On the host where you will run your Teleport instance, enable and start Teleport:

    sudo systemctl enable teleport
    sudo systemctl start teleport

    You can check the status of your Teleport instance with systemctl status teleport and view its logs with journalctl -fu teleport.

    warning

    Make sure that the Teleport process has its login UID unset. Otherwise, a session ID won't be set correctly in the emitted events. You can verify this by running the following command:

    cat /proc/$(pidof teleport)/loginuid

    The value should be set to 4294967295. If you start the Teleport process as a systemd service, its login UID will be unset.

Step 3/3. Trace SSH sessions with auditd​

There are a few ways to trace SSH sessions in Teleport. To interact with auditd events, we will use ausearch. If your system is missing that tool, consult your distribution documentation to check how to install it.

Search by a system user​

You can search events when logging in as a system user by using the -ua switch. You can check the UID of a user by using the id command:

$ id bob
uid=1000(bob) gid=1000(bob) groups=1000(bob)

Then you can use uid to search auditd logs:

ausearch -ua 1000 -m USER_LOGIN

Search by Teleport user​

Events sent to auditd by Teleport are augmented by the teleportUser field, which contains the name of the Teleport user. ausearch doesn't let you search by custom fields, but you can use grep for that:

ausearch -m USER_LOGIN | grep teleportUser=bob

Search by session ID​

If you want to find all events generated by a specific session, first, you need to find the session ID. You can do that by using:

ausearch  -m USER_LOGIN -x teleport --just-one

Then search events only related to that one session:

ausearch --session 42