Export Teleport Audit Events with Datadog

• A Teleport Team account. If you don't have an account, sign up to begin your free trial.

• The Enterprise tctl admin tool and tsh client tool, version >= 13.3.9.

  You can download these tools from the Cloud Downloads page.

• A running Teleport Enterprise cluster. For details on how to set this up, see the Enterprise Getting Started guide.

• The Enterprise tctl admin tool and tsh client tool version >= 14.0.0.

  You can download these tools by visiting your Teleport account workspace.

curl -L -O https://get.gravitational.com/teleport-event-handler-v14.0.0-darwin-amd64-bin.tar.gz
tar -zxvf teleport-event-handler-v14.0.0-darwin-amd64-bin.tar.gz
sudo ./teleport-event-handler/install

We currently only build the event handler plugin for amd64 machines. If your macOS machine uses Apple silicon, you will need to install Rosetta before you can run the event handler plugin. You can also build from source.

Ensure that you have Docker installed and running.

docker pull public.ecr.aws/gravitational/teleport-plugin-event-handler:14.0.0

To allow Helm to install charts that are hosted in the Teleport Helm repository, use helm repo add:

helm repo add teleport https://charts.releases.teleport.dev

To update the cache of charts from the remote repository, run helm repo update:

helm repo update

Ensure that you have Docker installed and running.

Run the following commands to build the plugin:

git clone https://github.com/gravitational/teleport-plugins.git --depth 1
cd teleport-plugins/event-handler/build.assets
make build

You can find the compiled binary within your clone of the teleport-plugins repo, with the file path, event-handler/build/teleport-event-handler.

You will need Go >= 1.21 installed.

Run the following commands on your Universal Forwarder host:

git clone https://github.com/gravitational/teleport-plugins.git --depth 1
cd teleport-plugins/event-handler
go build

The resulting executable will have the name event-handler. To follow the rest of this guide, rename this file to teleport-event-handler and move it to /usr/local/bin.

Run the configure command to generate a sample configuration. Replace teleport.example.com:443 with the DNS name and HTTPS port of Teleport's Proxy Service:

teleport-event-handler configure . teleport.example.com:443

Run the configure command to generate a sample configuration. Assign TELEPORT_CLUSTER_ADDRESS to the DNS name and port of your Teleport Auth Service or Proxy Service:

TELEPORT_CLUSTER_ADDRESS=mytenant.teleport.sh:443
docker run -v `pwd`:/opt/teleport-plugin -w /opt/teleport-plugin public.ecr.aws/gravitational/teleport-plugin-event-handler:14.0.0 configure . ${TELEPORT_CLUSTER_ADDRESS?}

In order to export audit events, you'll need to have the root certificate and the client credentials available as a secret. Use the following command to create that secret in Kubernetes:

kubectl create secret generic teleport-event-handler-client-tls --from-file=ca.crt=ca.crt,client.crt=client.crt,client.key=client.key

This will pack the content of ca.crt, client.crt, and client.key into the secret so the Helm chart can mount them to their appropriate path.

1. Retrieve your github authentication connector:

   tctl get github/github --with-secrets > github.yaml

   Note that the --with-secrets flag adds the value of spec.signing_key_pair.private_key to the github.yaml file. Because this key contains a sensitive value, you should remove the github.yaml file immediately after updating the resource.

2. Edit github.yaml, adding teleport-event-handler-impersonator to the teams_to_roles section.

   The team you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the team must include your user account and should be the smallest team possible within your organization.

   Here is an example:

     teams_to_roles:
       - organization: octocats
         team: admins
         roles:
           - access
   +       - teleport-event-handler-impersonator
   

3. Apply your changes:

   tctl create -f github.yaml

4. Sign out of the Teleport cluster and sign in again to assume the new role.

1. Retrieve your saml configuration resource:

   tctl get --with-secrets saml/mysaml > saml.yaml

   Note that the --with-secrets flag adds the value of spec.signing_key_pair.private_key to the saml.yaml file. Because this key contains a sensitive value, you should remove the saml.yaml file immediately after updating the resource.

2. Edit saml.yaml, adding teleport-event-handler-impersonator to the attributes_to_roles section.

   The attribute you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the group must include your user account and should be the smallest group possible within your organization.

   Here is an example:

     attributes_to_roles:
       - name: "groups"
         value: "my-group"
         roles:
           - access
   +       - teleport-event-handler-impersonator
   

3. Apply your changes:

   tctl create -f saml.yaml

4. Sign out of the Teleport cluster and sign in again to assume the new role.

1. Retrieve your oidc configuration resource:

   tctl get oidc/myoidc --with-secrets > oidc.yaml

   Note that the --with-secrets flag adds the value of spec.signing_key_pair.private_key to the oidc.yaml file. Because this key contains a sensitive value, you should remove the oidc.yaml file immediately after updating the resource.

2. Edit oidc.yaml, adding teleport-event-handler-impersonator to the claims_to_roles section.

   The claim you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the group must include your user account and should be the smallest group possible within your organization.

   Here is an example:

     claims_to_roles:
       - name: "groups"
         value: "my-group"
         roles:
           - access
   +       - teleport-event-handler-impersonator
   

3. Apply your changes:

   tctl create -f oidc.yaml

4. Sign out of the Teleport cluster and sign in again to assume the new role.

Like all Teleport users, teleport-event-handler needs signed credentials in order to connect to your Teleport cluster. You will use the tctl auth sign command to request these credentials for your plugin.

The following tctl auth sign command impersonates the teleport-event-handler user, generates signed credentials, and writes an identity file to the local directory:

tctl auth sign --user=teleport-event-handler --out=auth.pem

The plugin connects to the Teleport Auth Service's gRPC endpoint over TLS.

The identity file, auth.pem, includes both TLS and SSH credentials. The plugin uses the SSH credentials to connect to the Proxy Service, which establishes a reverse tunnel connection to the Auth Service. The plugin uses this reverse tunnel, along with your TLS credentials, to connect to the Auth Service's gRPC endpoint.

You will refer to this file later when configuring the plugin.

tsh login --proxy=teleport.example.com --ttl=60060

Next, create a Kubernetes secret for the Teleport identity file:

kubectl create secret generic teleport-event-handler-identity --from-file=auth_id=identity

These commands should result in a PEM-encoded file, identity, and a secret in Kubernetes with the name teleport-event-handler-identity.

storage = "./storage"
timeout = "10s"
batch = 20
namespace = "default"

[forward.fluentd]
ca = "/home/sasha/scripts/event-handler/ca.crt"
cert = "/home/sasha/scripts/event-handler/client.crt"
key = "/home/sasha/scripts/event-handler/client.key"
url = "https://localhost:8888/test.log"

[teleport]
addr = "teleport.example.com:443"
identity = "identity"

To start the event handler, run the following command:

teleport-event-handler start --config teleport-event-handler.toml

Use the following template to create teleport-plugin-event-handler-values.yaml:

eventHandler:
  storagePath: "./storage"
  timeout: "10s"
  batch: 20
  namespace: "default"

teleport:
  address: "example.teleport.com:443"
  identitySecretName: teleport-event-handler-identity

fluentd:
  url: "https://fluentd.fluentd.svc.cluster.local/events.log"
  sessionUrl: "https://fluentd.fluentd.svc.cluster.local/session.log"
  certificate:
    secretName: "teleport-event-handler-client-tls"
    caPath: "ca.crt"
    certPath: "client.crt"
    keyPath: "client.key"

persistentVolumeClaim:
  enabled: true

To start the event handler in Kubernetes, run the following command:

helm install teleport-plugin-event-handler teleport/teleport-plugin-event-handler \  --values teleport-plugin-event-handler-values.yaml \  --version 14.0.0