Skip to content

Commit 2f774fd

Browse files
benarentptgott
benarent
and
ptgott
authored
Docs: Teleport Panther Guide (#40736)
* wip Panther guide * extra formatting and content updates * Apply suggestions from code review Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com> * extra content updates, note machine id can't impersonate * Update Panther Docs and Image * Extra copy tweaks * Update Var Fomatting * switch to code to show formatting * cluster vars isn't working for this code segment, change back * Fix cspell lint * switchout image * Apply suggestions from code review --------- Co-authored-by: Paul Gottschling <paul.gottschling@goteleport.com>
1 parent 8c328a8 commit 2f774fd

File tree

5 files changed

+252
-0
lines changed

5 files changed

+252
-0
lines changed

‎docs/config.json

+4
Original file line numberDiff line numberDiff line change
@@ -814,6 +814,10 @@
814814
"title": "Export Audit Events to the Elastic Stack",
815815
"slug": "/management/export-audit-events/elastic-stack/"
816816
},
817+
{
818+
"title": "Export Audit Events to Panther",
819+
"slug": "/management/export-audit-events/panther/"
820+
},
817821
{
818822
"title": "Export Audit Events to Splunk",
819823
"slug": "/management/export-audit-events/splunk/"

‎docs/cspell.json

+1
Original file line numberDiff line numberDiff line change
@@ -846,6 +846,7 @@
846846
"thisisunsafe",
847847
"thred",
848848
"timechart",
849+
"timekey",
849850
"tlscacerts",
850851
"tlscert",
851852
"tlsexistingcasecretname",

‎docs/img/management/fluentd-diagram.png

158 KB
Loading

‎docs/img/management/panther-ingest.png

486 KB
Loading

‎docs/pages/management/export-audit-events/panther.mdx

+247
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,247 @@
1+
---
2+
title: Export Teleport Audit Events to Panther
3+
description: How to configure the Teleport Event Handler plugin and Fluentd to send audit logs to Panther
4+
---
5+
6+
Panther is a cloud-native security analytics platform. In this guide, we'll explain
7+
how to forward Teleport audit events to Panther using Fluentd.
8+
9+
## How it works
10+
11+
The Teleport Event Handler is designed to communicate with Fluentd using mTLS
12+
to establish a secure channel. In this setup, the Event Handler sends events to Fluentd, which forwards them to S3 to be ingested by Panther.
13+
14+
![Architecture of the setup shown in this guide](../../../img/management/fluentd-diagram.png)
15+
16+
## Prerequisites
17+
18+
(!docs/pages/includes/edition-prereqs-tabs.mdx!)
19+
20+
(!docs/pages/includes/machine-id/plugin-prerequisites.mdx!)
21+
22+
- A [Panther](https://panther.com/product/request-a-demo/) account.
23+
- A server, virtual machine, Kubernetes cluster, or Docker environment to run the
24+
Event Handler. The instructions below assume a local Docker container for testing.
25+
- Fluentd version v(=fluentd.version=) or greater. The Teleport Event Handler
26+
will create a new `fluent.conf` file you can integrate into an existing Fluentd
27+
system, or use with a fresh setup.
28+
- An S3 bucket to store the logs. Panther will ingest the logs from this bucket.
29+
30+
The instructions below demonstrate a local test of the Event Handler plugin on
31+
VM. You will need to adjust paths, ports, and domains for other environments.
32+
33+
- (!docs/pages/includes/tctl.mdx!)
34+
35+
## Step 1/7. Install the Event Handler plugin
36+
37+
The Teleport event handler runs alongside the Fluentd forwarder, receives events
38+
from Teleport's events API, and forwards them to Fluentd.
39+
40+
(!docs/pages/includes/install-event-handler.mdx!)
41+
42+
## Step 2/7. Generate a plugin configuration
43+
44+
(!docs/pages/includes/configure-event-handler.mdx!)
45+
46+
## Step 3/7. Create a user and role for reading audit events
47+
48+
(!docs/pages/includes/plugins/event-handler-role-user.mdx!)
49+
50+
## Step 4/7. Create teleport-event-handler credentials
51+
52+
In order for the Event Handler plugin to forward events from your Teleport cluster,
53+
it needs signed credentials from the cluster's certificate authority. The teleport-event-handler
54+
user cannot request this itself, and should use Teleport Machine ID to obtain the credentials.
55+
56+
Teleport Machine ID bot should leverage the `teleport-event-handler` role to request the credentials.
57+
Machine ID already impersonates roles when requesting credentials from the Teleport cluster.
58+
59+
### Export an identity file for the Event Handler plugin user
60+
61+
Give the plugin access to a Teleport identity file. We recommend using Machine
62+
ID for this in order to produce short-lived identity files that are less
63+
dangerous if exfiltrated, though in demo deployments, you can generate
64+
longer-lived identity files with `tctl`:
65+
66+
<Tabs>
67+
<TabItem label="Machine ID">
68+
(!docs/pages/includes/plugins/tbot-identity.mdx secret="teleport-event-handler-identity"!)
69+
</TabItem>
70+
<TabItem label="Long-lived identity files">
71+
(!docs/pages/includes/plugins/identity-export.mdx user="teleport-event-handler" secret="teleport-event-handler-identity"!)
72+
</TabItem>
73+
</Tabs>
74+
75+
## Step 5/7. Create a Dockerfile with Fluentd and the S3 plugin
76+
77+
To send logs to Panther, you need to use the Fluentd output plugin for S3. Create
78+
a `Dockerfile` with the following content:
79+
80+
```text
81+
FROM fluent/fluentd:edge
82+
USER root
83+
RUN fluent-gem install fluent-plugin-s3
84+
USER fluent
85+
```
86+
87+
Build the Docker image:
88+
89+
```shell
90+
$ docker build -t fluentd-s3 .
91+
```
92+
93+
<Admonition type="tip" title="Testing Locally?">
94+
95+
If you're running Fluentd in a local Docker container for testing, you can adjust
96+
the entrypoint to an interactive shell as the root user, so you can test the setup.
97+
98+
```code
99+
$ docker run -u $(id -u root):$(id -g root) -p 8888:8888 -v $(pwd):/keys -v \
100+
$(pwd)/fluent.conf:/fluentd/etc/fluent.conf --entrypoint=/bin/sh -i --tty fluentd-s3
101+
```
102+
103+
</Admonition>
104+
105+
### Configure Fluentd for Panther
106+
107+
When you run the Teleport Event Handler, it will create a `fluent.conf` file. This file needs to be updated
108+
to send logs to Panther. This means adding a `<filter>` and `<match>` section to the file. These sections
109+
will filter and format the logs before sending them to S3, The record_transformer is important to send the
110+
right date and time format for Panther.
111+
112+
```xml
113+
<!--
114+
# Below code is commented out as it's autogenerated in step 4 by teleport-event-handler
115+
fluent.conf
116+
This is a sample configuration file for Fluentd to send logs to S3.
117+
Created by the Teleport Event Handler plugin.
118+
Add the <filter> and <match> sections to the file.
119+
<source>
120+
@type http
121+
port 8888
122+
123+
<transport tls>
124+
client_cert_auth true
125+
ca_path "/keys/ca.crt"
126+
cert_path "/keys/server.crt"
127+
private_key_path "/keys/server.key"
128+
private_key_passphrase "AUTOGENERATED"
129+
</transport>
130+
131+
<parse>
132+
@type json
133+
json_parser oj
134+
135+
# This time format is used by Teleport Event Handler.
136+
time_type string
137+
time_format %Y-%m-%dT%H:%M:%S
138+
</parse>
139+
140+
# If the number of events is high, fluentd will start failing the ingestion
141+
# with the following error message: buffer space has too many data errors.
142+
# The following configuration prevents data loss in case of a restart and
143+
# overcomes the limitations of the default fluentd buffer configuration.
144+
# This configuration is optional.
145+
# See https://docs.fluentd.org/configuration/buffer-section for more details.
146+
<buffer>
147+
@type file
148+
flush_thread_count 8
149+
flush_interval 1s
150+
chunk_limit_size 10M
151+
queue_limit_length 16
152+
retry_max_interval 30
153+
retry_forever true
154+
</buffer>
155+
</source>
156+
-->
157+
<filter test.log>
158+
@type record_transformer
159+
enable_ruby true
160+
<record>
161+
time ${time.utc.strftime("%Y-%m-%dT%H:%M:%SZ")}
162+
</record>
163+
</filter>
164+
<match test.log>
165+
@type s3
166+
aws_key_id REPLACE_aws_access_key
167+
aws_sec_key REPLACE_aws_secret_access_key
168+
s3_bucket REPLACE_s3_bucket
169+
s3_region us-west-2
170+
path teleport/logs
171+
<buffer>
172+
@type file
173+
path /var/log/fluent/buffer/s3-events
174+
timekey 60
175+
timekey_wait 0
176+
timekey_use_utc true
177+
chunk_limit_size 256m
178+
</buffer>
179+
time_slice_format %Y%m%d%H%M%S
180+
<format>
181+
@type json
182+
</format>
183+
</match>
184+
<match session.*>
185+
@type stdout
186+
</match>
187+
```
188+
189+
Start the Fluentd container:
190+
191+
```shell
192+
$ docker run -p 8888:8888 -v $(pwd):/keys -v $(pwd)/fluent.conf:/fluentd/etc/fluent.conf fluentd-s3
193+
```
194+
This will start the Fluentd container and expose port 8888 for the Teleport Event Handler to send logs to.
195+
196+
## Step 6/7. Run the Teleport Event Handler plugin
197+
198+
### Configure the Event Handler
199+
200+
In this section, you will configure the Teleport Event Handler for your
201+
environment.
202+
203+
(!docs/pages/includes/plugins/finish-event-handler-config.mdx!)
204+
205+
Next, modify the configuration file as follows:
206+
207+
(!docs/pages/includes/plugins/config-toml-teleport.mdx!)
208+
209+
(!docs/pages/includes/plugins/machine-id-exporter-config.mdx!)
210+
211+
### Start the Teleport Event Handler
212+
213+
(!docs/pages/includes/start-event-handler.mdx!)
214+
215+
The Logs view in Panther should now report your Teleport cluster events.
216+
217+
## Step 7/7. Configure Panther to ingest logs from S3
218+
219+
Once logs are being sent to S3, you can configure Panther to ingest them. Follow
220+
the [Panther documentation](https://docs.panther.com/data-onboarding/supported-logs/teleport) to set
221+
up the S3 bucket as a data source.
222+
223+
![Panther Dashboard Example](../../../img/management/panther-ingest.png)
224+
225+
## Troubleshooting connection issues
226+
227+
If the Teleport Event Handler is displaying error logs while connecting to your
228+
Teleport Cluster, ensure that:
229+
230+
- The certificate the Teleport Event Handler is using to connect to your
231+
Teleport cluster is not past its expiration date. This is the value of the
232+
`--ttl` flag in the `tctl auth sign` command, which is 12 hours by default.
233+
- Ensure that in your Teleport Event Handler configuration file
234+
(`teleport-event-handler.toml`), you have provided the correct host *and* port
235+
for the Teleport Proxy Service.
236+
- Start the FluentD container prior to starting the Teleport Event Handler. The
237+
Event Handler will attempt to connect to FluentD immediately upon startup.
238+
239+
## Next steps
240+
241+
- Read more about
242+
[impersonation](../../access-controls/guides/impersonation.mdx)
243+
here.
244+
- Learn more about the [Panther Detections, Alerts and Notifications](https://panther.com/integrations/logs/teleport/).
245+
- To see all of the options you can set in the values file for the
246+
`teleport-plugin-event-handler` Helm chart, consult our [reference
247+
guide](../../reference/helm-reference/teleport-plugin-event-handler.mdx).

0 commit comments

Comments
 (0)