Skip to content

Commit

Permalink
Backport #11381 to branch/v8 (#11970)
Browse files Browse the repository at this point in the history 
* Add Teleport Cloud instructions to two guides

See #10634

Restricted Sessions for SSH

  While this already includes a compatibility note, I wanted to ensure
  that users would only see information relevant to the scope they had
  selected. Changes made:

  - Added a tabbed Prerequisites section

  - Removed instructions to install the Auth/Proxy that implicitly
    applied to all scopes

  - Misc style/grammar/clarity edits

BPF Session Recording

- Add scoped tabs
- Merge steps 2 and 3, which both involved examining the audit log to
  verify that Enhanced Session Recording is enabled
- Misc style/grammar/clarity tweaks

* Respond to PR feedback

- Fix style
- Flesh out the Node setup section
- Add Details about file-based event logs

* Respond to PR feedback

Restore the introductory section with minor copy-edits.
  • Loading branch information
@ptgott
ptgott authored Apr 15, 2022
1 parent e2e8d30 commit b0ed31a
Show file tree
Hide file tree
Showing 2 changed files with 159 additions and 81 deletions.
180 changes: 124 additions & 56 deletions docs/pages/server-access/guides/bpf-session-recording.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,24 +5,28 @@ h1: Enhanced Session Recording with BPF
videoBanner: 8uO5H-iYw5A
---

This guide explains Enhanced Session Recording for SSH with BPF and how to set
it up in your Teleport cluster.

Teleport's default [SSH and Kubernetes session recording](../../architecture/nodes.mdx#session-recording)
feature captures what is echoed to a terminal.

This has inherent advantages, for example, because no input is captured, Teleport
This has inherent advantages. For example, because no input is captured, Teleport
session recordings typically do not contain passwords that were entered into a terminal.

The disadvantage is that session recordings can be bypassed using several techniques:
The disadvantage is that there are several techniques for rendering session
recordings less useful:

- **Obfuscation**. For example, even though the command
`echo Y3VybCBodHRwOi8vd3d3LmV4YW1wbGUuY29tCg== | base64 --decode | sh` does not contain
`curl http://www.example.com`, when decoded, that is what is run.
- **Shell scripts**. For example, if a user uploads and executes a script, the commands run within the script are not captured, simply the output.
- **Shell scripts**. For example, if a user uploads and executes a script, the commands run within the script are not captured, only the output.
- **Terminal controls**. Terminals support a wide variety of controls including the ability for users to disable terminal echo. This is frequently used when requesting credentials. Disabling terminal echo allows commands to be run without being captured.

Furthermore, due to their unstructured nature, session recordings are difficult to
ingest and perform monitoring/alerting on.
ingest and perform monitoring and alerting on.

Teleport Enhanced Session Recording mitigates all three concerns by providing advanced security, greater logging capabilities, and better correlates a user with their activities.
Teleport Enhanced Session Recording mitigates all three concerns by providing advanced security and greater logging capabilities, and better correlates a user with their activities.

## Prerequisites

Expand All @@ -31,17 +35,24 @@ Teleport Enhanced Session Recording mitigates all three concerns by providing ad
- At least one host that you will use to run the Teleport Node Service. The host
must run Linux kernel 5.8 (or above).

<Admonition type="tip">
Our Standard Session Recording works with older Linux Kernels. View our [audit log docs](../../architecture/authentication.mdx#audit-log) for more details.
</Admonition>
You can check your kernel version using the `uname` command. The output should look
something like the following.

You can check your kernel version using the `uname` command. The output should look
something like the following.
```code
$ uname -r
# 5.8.17
```

```code
$ uname -r
# 5.8.17
```
See below for more details on the required versions for your Linux kernel and
distribution.

<Notice type="tip">

Our Standard Session Recording works with older Linux kernels. View
[Teleport Nodes](../../architecture/nodes.mdx#session-recording) for more
details.

</Notice>

### Linux distributions and supported kernels

Expand All @@ -57,19 +68,50 @@ $ uname -r
</tbody>
</table>

## Step 1/3. Install and configure Teleport node
(!docs/pages/includes/tctl.mdx!)

## Step 1/2. Configure a Teleport Node

### Install Teleport on your Node

On the host where you will run your Teleport Node, follow the instructions for
your environment to install Teleport.

(!docs/pages/includes/install-linux.mdx!)

### Generate a token

Use the `tctl` tool to generate an invite token that your Node will use to join
the cluster. In the following example, a new token is created with a TTL of five
minutes:

Follow our [installation instructions](../../installation.mdx) to install the Teleport Auth Service, Proxy Service, and Nodes. To get started with Teleport Cloud, sign up for a [free trial](https://goteleport.com/signup/).
```code
# Generate a short-lived invitation token for a new node:
$ tctl nodes add --ttl=5m --roles=node
# The invite token: (=presets.tokens.first=)
# You can also list all generated non-expired tokens:
$ tctl tokens ls
# Token Type Expiry Time
# ------------------------ ----------- ---------------
# (=presets.tokens.first=) Node 25 Sep 18 00:21 UTC
# ... or revoke an invitation token before it's used:
$ tctl tokens rm (=presets.tokens.first=)
```

### Create a configuration file

Set up the Teleport node with this `etc/teleport.yaml`. See our [configuration file setup](../../setup/reference/config.mdx) for more instructions.
Set up your Teleport Node with the following content in `/etc/teleport.yaml`.

```yaml
# Example config to be saved as etc/teleport.yaml
teleport:
nodename: graviton-node
auth_token: exampletoken
# The token you created earlier
auth_token: (=presets.tokens.first=)
auth_servers:
# Replace with IP of Teleport Auth server.
# Replace with the address of the Teleport Auth Service or Proxy Service.
- 127.0.0.1:3025
data_dir: /var/lib/teleport
proxy_service:
Expand All @@ -96,9 +138,22 @@ ssh_service:
cgroup_path: /cgroup2
```
## Step 2/3. Test by logging into node via Teleport
### Start Teleport on your Node
```code
$ teleport start
```

## Step 2/2. Inspect the audit log

<Tabs>
<TabItem scope={["oss", "enterprise"]} label="Self-Hosted">

Enhanced session recording events will be shown in Teleport's audit log, which
you can inspect by visiting Teleport's Web UI.

**Session with Enhanced Session Recording will be marked as 'true' in the logs.**
Events emitted via Enhanced Session Recording will include the
`"enhanced_recording": true` field in events similar to the following:

```json
{
Expand All @@ -119,9 +174,20 @@ ssh_service:
}
```

## Step 3/3. Inspect logs
If your Teleport cluster uses a file-based event log, you can examine your audit
log on the Teleport Auth Service host.

<Details title="Is my cluster using a file-based event log?" opened={false}>

Teleport's session recordings backend is configured via the
`teleport.storage.audit_sessions_uri` field. If a provided URI includes a scheme
that belongs to a cloud-based service (e.g., `s3://` or `dynamodb://`), you will
not be able to inspect session recordings in the filesystem of your Auth Service
host.

The resulting enhanced session recording will be shown in [Teleport's Audit Log](../../architecture/authentication.mdx#audit-log).
</Details>

Examine the contents of `/var/lib/teleport/log` as shown below:

```code
$ teleport-auth ~: tree /var/lib/teleport/log
Expand All @@ -145,39 +211,41 @@ $ teleport-auth ~: tree /var/lib/teleport/log
```

To quickly check the status of the audit log, you can simply tail the logs with
`tail -f /var/lib/teleport/log/events.log`, the resulting capture from Teleport will
`tail -f /var/lib/teleport/log/events.log`. The resulting capture from Teleport will
be a JSON log for each command and network request.
</TabItem>
<TabItem scope={["cloud"]} label="Teleport Cloud">

<Tabs>
<TabItem label="json">
```json
{"argv":["google.com"],"cgroup_id":4294968064,"code":"T4000I","ei":5,"event":"session.command","login":"root","namespace":"default","path":"/bin/ping","pid":2653,"ppid":2660,"program":"ping","return_code":0,"server_id":"96f2bed2-ebd1-494a-945c-2fd57de41644","sid":"44c6cea8-362f-11ea-83aa-125400432324","time":"2020-01-13T18:05:53.919Z","uid":"734930bb-00e6-4ee6-8798-37f1e9473fac","user":"benarent"}
```
</TabItem>

<TabItem label="json formatted">
```json
{
"argv":[
"google.com"
],
"cgroup_id":4294968064,
"code":"T4000I",
"ei":5,
"event":"session.command",
"login":"root",
"namespace":"default",
"path":"/bin/ping",
"pid":2653,
"ppid":2660,
"program":"ping",
"return_code":0,
"server_id":"96f2bed2-ebd1-494a-945c-2fd57de41644",
"sid":"44c6cea8-362f-11ea-83aa-125400432324",
"time":"2020-01-13T18:05:53.919Z",
"uid":"734930bb-00e6-4ee6-8798-37f1e9473fac",
"user":"benarent"
}
```
</TabItem>
Enhanced session recording events will be shown in Teleport's audit log, which
you can inspect by visiting Teleport's Web UI.

Sessions with Enhanced Session Recording will include the
`"enhanced_recording": true` field in events similar to the following:

```json
{
"code": "T2004I",
"ei": 23,
"enhanced_recording": true,
"event": "session.end",
"interactive": true,
"namespace": "default",
"participants": [
"benarent"
],
"server_id": "585fc225-5cf9-4e9f-8ff6-1b0fd6885b09",
"sid": "ca82b98d-1d30-11ea-8244-cafde5327a6c",
"time": "2019-12-12T22:44:46.218Z",
"uid": "83e67464-a93a-4c7c-8ce6-5a3d8802c3b2",
"user": "benarent"
}
```
</TabItem>
</Tabs>

## Next steps

- Read more about
[session recording](../../architecture/nodes.mdx#session-recording).
- See all configuration options for Enhanced Session Recording in our
[Configuration Reference](../../setup/reference/config.mdx).
60 changes: 35 additions & 25 deletions docs/pages/server-access/guides/restricted-session.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: Restricted Session for SSH
title: Restricted Sessions for SSH
description: How restrict what can be performed under an SSH session
h1: Restricted Session for SSH
h1: Restricted Sessions for SSH
videoBanner: DgFZpWszL4M
---

Expand Down Expand Up @@ -37,33 +37,37 @@ Teleport supports network restrictions with more types coming in the future.
</tbody>
</table>

(!docs/pages/includes/tctl.mdx!)

## Network Restrictions

Network restrictions work similar to a firewall but with several differences:
Network restrictions work similarly to a firewall but with several differences:
1. Firewall rules apply to the entire machine whereas network restrictions are applied
only to SSH sessions.
2. Whereas firewall typically blocks ingress (inbound) connections, network restrictions
block egress (outbound) connections.
3. Firewall rules are typically static but Restricted Session comes with an API allowing the
rules to be dynamically updated across the entire fleet.
3. Firewall rules are typically static but Teleport provides an API for
Restricted Sessions that allows the rules to be dynamically updated across
the entire fleet.

## Step 1/4. Install and configure Teleport node
## Step 1/4. Install and configure a Teleport Node

Follow our [installation instructions](../../installation.mdx) to install Teleport Auth Service, Proxy Service, and Nodes. For Teleport's managed deployments of the Auth Service and Proxy Service, sign up for a [free trial](https://goteleport.com/signup/) of Teleport Cloud.
Set up your Teleport Node with the following content in `/etc/teleport.yaml`.

Set up the Teleport node with this `/etc/teleport.yaml`. See our [configuration file setup](../../setup/reference/config.mdx) for more instructions.
<Notice type="warning">

<Admonition type="note">
Restricted Session requires Enhanced Recording to be enabled as well. This requirement will be removed in the future.
</Admonition>
Restricted Sessions require Enhanced Recording to be enabled. This
requirement will be removed in the future.

</Notice>

```yaml
# Example config to be saved as /etc/teleport.yaml
teleport:
nodename: graviton-node
auth_token: exampletoken
auth_servers:
# Replace with IP of Teleport Auth server.
# Replace with the address of the Teleport Auth Server.
- 127.0.0.1:3025
data_dir: /var/lib/teleport
proxy_service:
Expand All @@ -85,15 +89,15 @@ ssh_service:
## Step 2/4. Define a network restrictions policy
Create a file `netpolicy.yaml`:
Create a file called `netpolicy.yaml`:

```yaml
kind: network_restrictions
version: v4
metadata:
name: network-restrictions
spec:
# When Restricted Session is enabled, the network policy becomes
# When Restricted Sessions are enabled, the network policy becomes
# "deny-all". Must add back the ranges to allow
allow:
# Allow LAN access
Expand Down Expand Up @@ -122,15 +126,16 @@ $ tctl create -f netpolicy.yaml
# network restrictions have been updated
```

<Admonition type="note">
- If the Restricted Session is not enabled in `teleport.yaml`, all network operations will be allowed.
- When the Restricted Session is enabled but `network_restrictions` object has not been created via `tctl` or the API,
the default policy stays allow-all.
- However when the `network_restrictions` object is created, the default policy switches to deny-all.
Be sure to add back all the necessary ranges into the allow list.
</Admonition>
If Restricted Sessions are not enabled in `teleport.yaml`, all network
operations will be allowed. When Restricted Sessions are enabled but a
`network_restrictions` object has not been created via `tctl` or the API, the
default policy stays allow-all.

## Step 3/4. Test by logging into node via Teleport
However when the `network_restrictions` object is created, the default policy
switches to deny-all. If you expect network operations to target certain
IP ranges, be sure to state these within the `allow` section.

## Step 3/4. Test Restricted Sessions

```code
$ curl -v https://google.com
Expand All @@ -146,7 +151,8 @@ $ curl -v https://google.com

## Step 4/4. Inspect logs

The audit log will contain an entry with `session.network` event (there may be more entries present for the same `curl` command):
The Teleport audit log will contain an entry with a `session.network` event (there may be
more entries present for the same `curl` command):

```json
{
Expand Down Expand Up @@ -174,11 +180,15 @@ The audit log will contain an entry with `session.network` event (there may be m
```

This is the same event that is issued by Enhanced Recording. You can differentiate them by the `action` field.
Enhanced Recording sets the `action` to `0` (`OBSERVED`) while Restricted Session sets this value to `1` (`DENIED`).
Enhanced Recording sets the `action` to `0` (`OBSERVED`) while a Restricted Session sets this value to `1` (`DENIED`).

<Admonition type="tip">
Restricted Session requires Enhanced Recording to be enabled as well. This requirement will be removed in the future.
To quickly check the status of the audit log, you can simply tail the logs with
`tail -f /var/lib/teleport/log/events.log`, the resulting capture from Teleport will
be a JSON log for each command and network request.
</Admonition>

## Next steps

- See the [Teleport Configuration Reference](../../setup/reference/config.mdx) for more
information on configuring Restricted Sessions.

0 comments on commit b0ed31a

Please sign in to comment.