From 20b6efee3bb7c2fcc89c9d0436c94bad4549c189 Mon Sep 17 00:00:00 2001 From: Ben Arent Date: Tue, 3 Dec 2019 16:30:45 -0800 Subject: [PATCH 1/3] WIP Enhanced Session Recording --- docs/4.2.yaml | 6 +- docs/4.2/admin-guide.md | 26 +++ .../features/enhanced_session_recording.md | 180 ++++++++++++++++++ 3 files changed, 210 insertions(+), 2 deletions(-) create mode 100644 docs/4.2/features/enhanced_session_recording.md diff --git a/docs/4.2.yaml b/docs/4.2.yaml index 07fbf161eb6a0..657b398be5e26 100644 --- a/docs/4.2.yaml +++ b/docs/4.2.yaml @@ -6,8 +6,8 @@ site_author: Gravitational Inc copyright: Gravitational Inc, 2016-19 # output directory: -site_dir: ../build/docs/4.1 -docs_dir: "4.1" +site_dir: ../build/docs/4.2 +docs_dir: "4.2" theme: readthedocs theme_dir: theme @@ -30,6 +30,8 @@ pages: - Admin Manual: admin-guide.md - Installation: installation.md - FAQ: faq.md + - Teleport Features: + - Enhanced Session Recording: features/enhanced_session_recording.md - Infrastructure Guides: - AWS: aws_oss_guide.md - Kubernetes Guide: kubernetes_ssh.md diff --git a/docs/4.2/admin-guide.md b/docs/4.2/admin-guide.md index e18e7bb833ead..56b43dba48cbd 100644 --- a/docs/4.2/admin-guide.md +++ b/docs/4.2/admin-guide.md @@ -415,6 +415,26 @@ ssh_service: # set to false, can be set true here or as a command line flag. permit_user_env: false + # Enhanced Session Recording was introduced with Teleport 4.2. For more details + # see + enhanced_recording: + # Enable or disable enhanced auditing for this node. Default value: + # false. + enabled: true + + # command_buffer_size is optional with a default value of 8 pages. + command_buffer_size: 8 + + # disk_buffer_size is optional with default value of 128 pages. + disk_buffer_size: 128 + + # network_buffer_size is optional with default value of 8 pages. + network_buffer_size: 8 + + # Controls where cgroupv2 hierarchy is mounted. Default value: + # /cgroup2. + cgroup_path: /cgroup2 + # configures PAM integration. see below for more details. pam: enabled: no @@ -1033,6 +1053,8 @@ the audit log: replayed later. The recording is done by the nodes themselves, by default, but can be configured to be done by the proxy. +3. **Optional: Enhanced Session Recording** + Refer to the ["Audit Log" chapter in the Teleport Architecture](architecture/teleport_auth.md#audit-log) to learn more about how the audit Log and session recording are designed. @@ -1100,11 +1122,15 @@ The possible event types are: | session.end | An interactive shell session has ended.| | session.join | A new user has joined the existing interactive shell session.| | session.leave | A user has left the session.| +| session.disk | A list of files opened during the session. *Requires Enhanced Session Recording*. | +| session.network | A list of network connections made during the session. *Requires Enhanced Session Recording*. | +| session.command | A list of commands ran during the session. *Requires Enhanced Session Recording*. | | exec | Remote command has been executed via SSH, like `tsh ssh root@node ls /` . The following fields will be logged: `{"command": "ls /", "exitCode": 0, "exitError": ""}` | | scp | Remote file copy has been executed. The following fields will be logged: `{"path": "/path/to/file.txt", "len": 32344, "action": "read" }` | | resize | Terminal has been resized.| | user.login | A user logged into web UI or via tsh. The following fields will be logged: `{"user": "alice@example.com", "method": "local"}` .| + ### Recorded Sessions In addition to logging `session.start` and `session.end` events, Teleport also diff --git a/docs/4.2/features/enhanced_session_recording.md b/docs/4.2/features/enhanced_session_recording.md new file mode 100644 index 0000000000000..b456d3d8a0e98 --- /dev/null +++ b/docs/4.2/features/enhanced_session_recording.md @@ -0,0 +1,180 @@ +# Enhanced Session Recording + +Teleport standard session recordings only capture what is echoed to a terminal. +This has inherent advantages, for example because no input is captured, Teleport +session recordings typically do not contain passwords that were ended into a terminal. + +The disadvantages is that session recordings can by bypassed using several techniques. + +- **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. +- **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. + +# Requirements: + +## 1. Check / Patch Kernel. +Teleport 4.2 with Enhanced Session Recording requires Linux kernel 4.18 (or above) as +well as kernel headers. + +You can check your kernel version using the `uname` command. The output should look +something like the following. + +``` +$ uname -a +Linux ip-172-31-43-104.ec2.internal 4.19.72-25.58.amzn2.x86_64 x86_64 x86_64 x86_64 GNU/Linux +``` + + +### Ubuntu + +| | | Kernel Version | +|-------|-------------------|-----------------------| +| 18.10 | Cosmic Cuttlefish | 4.18 [Patch Kernel](http://www.theubuntumaniac.com/2018/11/update-install-kernel-4191-stable-on.html) | +| 19.04 | Disco Dingo | 5.0 ✅ | +| 19.10 | Eoan Ermine | 5.3 ✅ | + +### Debian + +| | | Kernel Version | +|-----|---------------------|---------------------------| +| 9 | Debian Stretch | 4.9.0-6 [Patch Kernel](https://wiki.debian.org/HowToUpgradeKernel) | +| 10 | Buster | 4.19 ✅ | + +### CentOS +| | Kernel Version | +|---------------|------------------------| +| 8.0-1905 | 4.18.0.80 ✅ | + +### Red Hat +| | Kernel Version | +|---------------------|------------------------| +| Enterprise Linux 8 | 4.18.0-147 ✅ | + +### Amazon Linux +We recommend using `Amazon Linux 2` to install and use Linux kernel 4.19 using +`sudo amazon-linux-extras` install kernel-ng and rebooting your instance. + +### archlinux +| | Kernel Version | +|---------------------|------------------------| +| 2019.12.01 | 5.3.13 ✅ | + +## 2. Install BCC Tools + +Run the following script to download the prerequisites to build BCC tools, building LLVM and Clang targeting BPF byte code, and then building and installing BCC tools. + +!!! note + We plan have plans to remove this step after we've moved our of our beta. + +```sh +#!/bin/bash + +set -e + +if [[ $EUID -ne 0 ]]; then + echo "Please run this script as root or sudo." + exit 1 +fi + +# Create a temporary to build tooling in. +BUILD_DIR=$(mktemp -d) +cd $BUILD_DIR +echo "Building in $BUILD_DIR." + +# Install Extra Packages for Enterprise Linux (EPEL) +yum install -y epel-release +yum update -y + +# Install development tools. +yum groupinstall -y "Development tools" +yum install -y elfutils-libelf-devel cmake3 git bison flex ncurses-devel + +# Download and install LLVM and Clang. Build them with BPF target. +curl -LO http://releases.llvm.org/7.0.1/llvm-7.0.1.src.tar.xz +curl -LO http://releases.llvm.org/7.0.1/cfe-7.0.1.src.tar.xz +tar -xf cfe-7.0.1.src.tar.xz +tar -xf llvm-7.0.1.src.tar.xz + +mkdir clang-build +mkdir llvm-build + +cd llvm-build +cmake3 -G "Unix Makefiles" -DLLVM_TARGETS_TO_BUILD="BPF;X86" \ + -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr ../llvm-7.0.1.src +make +make install +cd .. + +cd clang-build +cmake3 -G "Unix Makefiles" -DLLVM_TARGETS_TO_BUILD="BPF;X86" \ + -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr ../cfe-7.0.1.src +make +make install +cd .. + +# Install BCC. +git clone https://github.com/iovisor/bcc.git +mkdir bcc/build; cd bcc/build +cmake3 .. -DCMAKE_INSTALL_PREFIX=/usr +make +make install + +# Install is done. +rm -fr $BUILD_DIR +echo "Install is complete, try running /usr/share/bcc/tools/execsnoop to verify install." +``` + +## 3. Install & Configure Teleport Node + +Follow our [installation instructions](../installation.md) to install Teleport Auth, Proxy +and Nodes. + +Setup the Teleport node with this `etc/teleport.yaml` see our [configuration file setup](../admin-guide/#configuration) for more instructions. + + +``` +# Example Config to be saved as etc/teleport.yaml +teleport: + nodename: graviton-node + auth_token: exampletoken + auth_servers: + - 127.0.0.1:5000 + data_dir: /var/lib/teleport +proxy_service: + enabled: no +auth_service: + enabled: no +ssh_service: + enabled: yes + enhanced_recording: + # Enable or disable enhanced auditing for this node. Default value: false. + enabled: true + + # command_buffer_size is optional with a default value of 8 pages. + command_buffer_size: 8 + + # disk_buffer_size is optional with default value of 128 pages. + disk_buffer_size: 128 + + # network_buffer_size is optional with default value of 8 pages. + network_buffer_size: 8 + + # Controls where cgroupv2 hierarchy is mounted. Default value: + # /cgroup2. + cgroup_path: /cgroup2 +``` + +## 4. Test by logging into node via Teleport. +[Add image here] + + + +## 5. Inspect Logs +[Show new file structure] From 7c7762a72d598085e11999abe1c75616e2d9b26f Mon Sep 17 00:00:00 2001 From: Ben Arent Date: Tue, 3 Dec 2019 16:59:39 -0800 Subject: [PATCH 2/3] Add notes that all parts of the system need to be upgraded. --- docs/4.2/features/enhanced_session_recording.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/4.2/features/enhanced_session_recording.md b/docs/4.2/features/enhanced_session_recording.md index b456d3d8a0e98..e7129308991ca 100644 --- a/docs/4.2/features/enhanced_session_recording.md +++ b/docs/4.2/features/enhanced_session_recording.md @@ -17,6 +17,11 @@ ability for users to disable terminal echo. This is frequently used when request Furthermore, due to their unstructured nature, session recordings are difficult to ingest and perform monitoring/alerting on. +!!! Note: + + Enhanced Session Recording requires all parts of the Teleport system to be running + 4.2+. + # Requirements: ## 1. Check / Patch Kernel. From 1e89ad182e35206beed2727a8ce1ce20911b2899 Mon Sep 17 00:00:00 2001 From: Ben Arent Date: Wed, 11 Dec 2019 14:37:14 -0800 Subject: [PATCH 3/3] Addressing feedback from RJ --- .../features/enhanced_session_recording.md | 36 +++++++++++-------- 1 file changed, 21 insertions(+), 15 deletions(-) diff --git a/docs/4.2/features/enhanced_session_recording.md b/docs/4.2/features/enhanced_session_recording.md index e7129308991ca..3f4d28dc6a0c4 100644 --- a/docs/4.2/features/enhanced_session_recording.md +++ b/docs/4.2/features/enhanced_session_recording.md @@ -64,7 +64,7 @@ Linux ip-172-31-43-104.ec2.internal 4.19.72-25.58.amzn2.x86_64 x86_64 x86_64 x86 ### Amazon Linux We recommend using `Amazon Linux 2` to install and use Linux kernel 4.19 using -`sudo amazon-linux-extras` install kernel-ng and rebooting your instance. +`sudo amazon-linux-extras install kernel-ng` and rebooting your instance. ### archlinux | | Kernel Version | @@ -76,7 +76,12 @@ We recommend using `Amazon Linux 2` to install and use Linux kernel 4.19 using Run the following script to download the prerequisites to build BCC tools, building LLVM and Clang targeting BPF byte code, and then building and installing BCC tools. !!! note - We plan have plans to remove this step after we've moved our of our beta. + + We plan to soon support installing bcc-tools from packages instead of compiling them yourself to make taking advantage of enhanced session recording easier. + +**Example Script to install relevant bcc packages for CentOS** +Follow [bcc documentation](https://github.com/iovisor/bcc/blob/master/INSTALL.md#debian---source) on how to install the relevant tooling for other operating systems. + ```sh #!/bin/bash @@ -126,6 +131,7 @@ cd .. # Install BCC. git clone https://github.com/iovisor/bcc.git +cd bcc && git checkout v0.11.0 mkdir bcc/build; cd bcc/build cmake3 .. -DCMAKE_INSTALL_PREFIX=/usr make @@ -144,7 +150,7 @@ and Nodes. Setup the Teleport node with this `etc/teleport.yaml` see our [configuration file setup](../admin-guide/#configuration) for more instructions. -``` +```yaml # Example Config to be saved as etc/teleport.yaml teleport: nodename: graviton-node @@ -158,22 +164,22 @@ auth_service: enabled: no ssh_service: enabled: yes - enhanced_recording: - # Enable or disable enhanced auditing for this node. Default value: false. - enabled: true + enhanced_recording: + # Enable or disable enhanced auditing for this node. Default value: false. + enabled: true - # command_buffer_size is optional with a default value of 8 pages. - command_buffer_size: 8 + # Optional: command_buffer_size is optional with a default value of 8 pages. + command_buffer_size: 8 - # disk_buffer_size is optional with default value of 128 pages. - disk_buffer_size: 128 + # Optional: disk_buffer_size is optional with default value of 128 pages. + disk_buffer_size: 128 - # network_buffer_size is optional with default value of 8 pages. - network_buffer_size: 8 + # Optional: network_buffer_size is optional with default value of 8 pages. + network_buffer_size: 8 - # Controls where cgroupv2 hierarchy is mounted. Default value: - # /cgroup2. - cgroup_path: /cgroup2 + # Optional: Controls where cgroupv2 hierarchy is mounted. Default value: + # /cgroup2. + cgroup_path: /cgroup2 ``` ## 4. Test by logging into node via Teleport.