Skip to content

Commit 5bf7446

Browse files
geanboegmangeanboegman
committed
- Add updates for setting up additional kernels.
- Filter out the token when logging the imds call.
1 parent 1b44cbd commit 5bf7446

File tree

4 files changed

+398
-47
lines changed

4 files changed

+398
-47
lines changed

‎README.md

+254-22
Original file line numberDiff line numberDiff line change
@@ -1,42 +1,188 @@
11
# AWS ImdsPacketAnalyzer
22

3-
The AWS ImdsPacketAnalyzer is a tool that traces TCP interactions with the EC2 Instance Metadata Service (IMDS). This can assist in identifying the processes making IMDSv1 calls on a host. Traces contain the `pid`, the `argv` used to launch the process, and the parent `pids` up to four levels deep. This information allow you to identify a Process making IMDSv1 calls for further investigation.
3+
- [Packages - Installing BCC](#packages---installing-bcc)
4+
- [Amazon Linux 2023](#amazon-linux-2023)
5+
- [Amazon Linux 2](#amazon-linux-2)
6+
- [Amazon Linux 1, 2018.03](#amazon-linux-1-201803)
7+
- [Debian 11](#debian-11)
8+
- [Debian 10](#debian-10)
9+
- [Ubuntu 20 / 22](#ubuntu-20--22)
10+
- [RHEL 8 / 9](#rhel-8--9)
11+
- [SLES 15](#sles-15)
12+
- [Windows](#windows)
13+
- [Usage](#usage)
14+
- [Amazon Linux 2023](#amazon-linux-2023-1)
15+
- [Amazon Linux 2](#amazon-linux-2-1)
16+
- [Amazon Linux 1](#amazon-linux-1)
17+
- [Debian 11](#debian-11-1)
18+
- [Debian 10](#debian-10-1)
19+
- [Ubuntu 20 / 22](#ubuntu-20--22-1)
20+
- [RHEL 8 / 9](#rhel-8--9-1)
21+
- [SLES 15](#sles-15-1)
22+
- [Windows](#windows-1)
23+
- [Logging](#logging)
24+
- [Running the tool as a service](#running-the-tool-as-a-service)
25+
- [Activating the tool as a service](#activating-the-tool-as-a-service)
26+
- [Deactivating the tool as a service](#deactivating-the-tool-as-a-service)
27+
- [Limitations](#limitations)
428

529

6-
## Installation
7-
The ImdsPacketAnalyzer leverages the [BCC (BPF Compiler Collection)](https://github.com/iovisor/bcc). In order to successfully run the analyzer the BCC pre-requisites need to be installed.
30+
# Introduction
31+
32+
The AWS ImdsPacketAnalyzer is a tool that traces TCP interactions with the EC2 Instance Metadata Service (IMDS). This can assist in identifying the processes making IMDSv1 calls on a host. Traces contain the `pid`, the `argv` used to launch the process, and the parent `pids` up to four levels deep. This information allow you to identify a Process making IMDSv1 calls for further investigation.
33+
34+
The ImdsPacketAnalyzer leverages the [BCC (BPF Compiler Collection)](https://github.com/iovisor/bcc/blob/master/INSTALL.md#Amazon-Linux-2---Binary). In order to successfully run the analyzer the BCC pre-requisites need to be installed.
35+
36+
# Packages - Installing BCC
37+
For hosts with internet access, the install script can be used. It is advised that this script only be run on non-production instances. Installation will update dependancies and may affect other functionality.
38+
For instances without internet access you will need to share the files on an S3 folder.
39+
```
40+
sudo bash install-deps.sh
41+
```
42+
---
43+
44+
**OR** run the following commands per OS
45+
46+
47+
## Amazon Linux 2023
48+
49+
Install BCC
850

9-
### Amazon Linux 2 (AL2)
10-
For AL2 hosts with internet access, either a installation script,
1151
```
12-
sudo ./install-deps.sh
52+
sudo dnf install bcc-tools
1353
```
14-
or, the steps detailed in the [BCC documentation](https://github.com/iovisor/bcc/blob/master/INSTALL.md#Amazon-Linux-2---Binary)
54+
---
55+
56+
## Amazon Linux 2
57+
58+
Install [BCC (BPF Compiler Collection)](https://github.com/iovisor/bcc/blob/master/INSTALL.md#Amazon-Linux-2---Binary):
1559

1660
```
1761
sudo amazon-linux-extras enable BCC
18-
<!-- @import "[TOC]" {cmd="toc" depthFrom=1 depthTo=6 orderedList=false} -->
19-
2062
sudo yum install kernel-devel-$(uname -r)
2163
sudo yum install bcc
2264
```
23-
can be used. For instances without internet access you will need to share the files on an S3 folder.
24-
25-
### Amazon Linux 1, 2018.03
65+
---
2666

67+
## Amazon Linux 1, 2018.03
68+
2769
Install [BCC (BPF Compiler Collection)](https://github.com/iovisor/bcc/blob/master/INSTALL.md#Amazon-Linux-1---Binary):
28-
70+
2971
```
3072
sudo yum install kernel-headers-$(uname -r | cut -d'.' -f1-5)
3173
sudo yum install kernel-devel-$(uname -r | cut -d'.' -f1-5)
3274
sudo yum install bcc
3375
```
76+
---
77+
78+
## Debian 11
79+
80+
```
81+
echo deb http://cloudfront.debian.net/debian sid main | sudo tee -a /etc/apt/sources.list
82+
sudo apt-get update
83+
sudo apt-get install -y bpfcc-tools libbpfcc libbpfcc-dev linux-headers-$(uname -r)
84+
sudo apt-get install linux-headers-$(uname -r) bcc
85+
```
86+
---
87+
88+
## Debian 10
89+
90+
Note : During the Dependency installation, the ["libcrypt1"](https://www.mail-archive.com/debian-bugs-dist@lists.debian.org/msg1818037.html) related error occurs so the execution has step to fix and continue with the installation process further, also the OS libraries can cause the restart of the system releated services like sshd and crond.
91+
92+
```
93+
echo deb http://cloudfront.debian.net/debian sid main | sudo tee -a /etc/apt/sources.list
94+
sudo -i # Need to switch as root user in the CLI before running below command
95+
apt-get update
96+
#Set the environment variable DEBIAN_FRONTEND to 'noninteractive' to avoid the prompts and accept the default answers
97+
export DEBIAN_FRONTEND=noninteractive
98+
apt-get install -y bpfcc-tools libbpfcc libbpfcc-dev linux-headers-$(uname -r) bcc --no-install-recommends
99+
#Steps to fix the libcrypt1 error
100+
cd /tmp/
101+
apt -y download libcrypt1
102+
dpkg-deb -x libcrypt1* .
103+
cp -av lib/x86_64-linux-gnu/* /lib/x86_64-linux-gnu/
104+
#Re-run the install command
105+
apt-get install -y bpfcc-tools libbpfcc libbpfcc-dev linux-headers-$(uname -r) bcc --no-install-recommends
106+
apt install -y --fix-broken
107+
# Run the install command
108+
apt-get install -y bpfcc-tools libbpfcc libbpfcc-dev linux-headers-$(uname -r) bcc --no-install-recommends
109+
```
110+
---
111+
112+
## Ubuntu 20 / 22
113+
```
114+
sudo apt install -y bison build-essential cmake flex git libedit-dev libllvm14 llvm-14-dev libclang-14-dev python3 zlib1g-dev libelf-dev libfl-dev python3-distutils
115+
git clone https://github.com/iovisor/bcc.git
116+
mkdir bcc/build; cd bcc/build
117+
cmake ..
118+
make
119+
sudo make install
120+
cmake -DPYTHON_CMD=python3 .. # build python3 binding
121+
pushd src/python/
122+
make
123+
sudo make install
124+
popd
125+
sudo apt-get install linux-headers-$(uname -r)
126+
```
127+
---
128+
129+
## RHEL 8 / 9
130+
131+
```
132+
sudo yum -y install bcc-tools libbpf
133+
```
134+
---
135+
136+
## SLES 15
137+
```
138+
sudo zypper ref
139+
sudo zypper in bcc-tools bcc-examples
140+
sudo zypper in --oldpackage kernel-default-devel-$(zypper se -s kernel-default-devel | awk '{split($0,a,"|"); print a[4]}' | grep $(uname -r | awk '{gsub("-default", "");print}') | sed -e 's/^[ \t]*//' | tail -n 1)
141+
```
142+
143+
---
144+
145+
## WINDOWS
146+
147+
INSTALL PYTHON
148+
- Check if Python is installed with ```python -V```
149+
- Download python3 msi https://www.python.org/downloads/
150+
- Select to add python.exe to PATH
151+
152+
153+
INSTALL PIP
154+
- Check if PIP is installed with ```pip help```
155+
- Download PIP ```curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py```
156+
- Install with ```python get-pip.py```
157+
158+
159+
INSTALL GIT
160+
- Check if GIT is installed with ```git version```
161+
- Download ad install the MSI for Windows via ```https://git-scm.com/download/win```
162+
163+
164+
INSTALL AWS CLI
165+
- Run ```msiexec.exe /i https://awscli.amazonaws.com/AWSCLIV2.msi```
166+
- Run and configure the CLI with ```aws configure```
167+
- Ensure EC2 Instance IAM Profile is assigned with access to Cloudwatch.
168+
169+
170+
INSTALL METABADGER (https://github.com/salesforce/metabadger)
171+
- Run ```pip3 install --user metabadger```
172+
- Go to working directory ```cd C:\<Users>\<Administrator>\AppData\Roaming\Python\Python311\scripts```
173+
174+
---
34175

35176
**Note:** Troubleshooting + Installation on other distros please see: [BCC (BPF Compiler Collection)](https://github.com/iovisor/bcc/blob/master/INSTALL.md)
36177

178+
---
37179

38180
## Usage
39-
BCC require that the analyze is run with root permissions. Typically you can execute the following script `sudo python3 src/imds_snoop.py`. IMDS calls will be logged to the console and to a log file by default (see [logging.conf](logging.conf)).
181+
BCC require that the analyze is run with root permissions. Typically, you can execute the following script and IMDS calls will be logged to the console and to a log file by default (see [logging.conf](logging.conf)).
182+
```
183+
sudo python3 src/imds_snoop.py
184+
```
185+
40186

41187
#### Example v1 call:
42188
The following IMDSv1 curl command
@@ -47,8 +193,77 @@ will result the following analyzer output
47193
```
48194
IMDSv1(!) (pid:6028:curl argv:curl http://169.254.169.254/latest/meta-data/) called by -> (pid:6027:makeCalls.sh argv:/bin/bash ./makeCalls.sh) -> (pid:4081:zsh argv:-zsh) -> (pid:4081:sshd argv:sshd: kianred@pts/0)
49195
```
196+
---
197+
198+
## Amazon Linux 2023
199+
```
200+
sudo python3 src/imds_snoop.py
201+
```
202+
---
203+
204+
## Amazon Linux 2
205+
```
206+
sudo python3 src/imds_snoop.py
207+
```
208+
---
209+
210+
## Amazon Linux 1
211+
```
212+
sudo python3 src/imds_snoop.py
213+
```
214+
---
215+
216+
## Debian 11
217+
```
218+
sudo python3 src/imds_snoop.py
219+
```
220+
---
221+
222+
## Debian 10
223+
```
224+
sudo python3 src/imds_snoop.py
225+
```
226+
---
227+
228+
## Ubuntu 20 / 22
229+
```
230+
sudo LD_PRELOAD=/home/ubuntu/bcc/build/src/cc/libbcc.so.0 PYTHONPATH=/home/ubuntu/bcc/build/src/python src/imds_snoop.py
231+
```
232+
---
233+
234+
## RHEL 8 / 9
235+
```
236+
sudo python3 src/imds_snoop.py
237+
```
238+
---
50239

51-
## Logging
240+
## SLES 15
241+
```
242+
sudo python3 src/imds_snoop.py
243+
```
244+
---
245+
246+
## WINDOWS
247+
- From the Working directory E.g ```cd C:\<Users>\<Administrator>\AppData\Roaming\Python\Python311\scripts```
248+
- Run to view IMDSv1 calls: ```metabadger cloudwatch-metrics --region us-east-1```
249+
250+
The output table will highlight if the instance has made IMDSv1 calls
251+
252+
To find the specific app that was making the IMDSv1 calls, use the inbuilt Windows Resource Monitor Network monitor to find the Image and PID of the application making calls.
253+
254+
To do this open Resource Monitor (Start->Search ->Resource Monitor) and click on the Network tab.
255+
Then look for calls in the Network Activity section made to either the IP or DNS entries listed:
256+
- IP: ```169.254.169.254```
257+
- DNS: instance-data.<region>.compute.internal E.g ```instance-data.us-east-1.compute.internal```
258+
259+
Network Analyzer will show the calls and you should proceed to update the software/application
260+
261+
More details and thanks to https://github.com/salesforce/metabadger and https://www.greystone.co.uk/2022/03/24/how-greystone-upgraded-its-aws-ec2-instances-to-use-instance-meta-data-service-version-2-imdsv2/
262+
263+
264+
---
265+
266+
# Logging
52267
The ImdsPacketAnalyzer will also capture IMDS calls to log files. Log entries follow the format: `[Time] [Level] [message]` where:
53268
- **Time:** the time at which the IMDS call was made in the format: `%Y-%m-%dT%H:%M:%S` eg.) [2022-12-20T12:57:51]
54269
- **Level:** the level of the log entry, where IMDSv2 calls are logged at `INFO` level and IMDSv1 calls are logged at `WARNING` level
@@ -80,35 +295,52 @@ By default:
80295
### Analyzing log files
81296
**Assuming default logging setup:**
82297
- Running the command `cat /var/log/imds-trace.* | grep WARNING` will output all IMDSv1 calls to the terminal.
83-
- Note that this grep will only identify the call, sometimes the calls leading up to the V1 call can provide additional context.
298+
- Note that this grep will only identify the call, sometimes the calls leading up to the V1 call can provide additional context.
84299

85-
## Running the tool as a service
300+
# Running the tool as a service
86301

87-
### Activating the tool as a service
302+
## Activating the tool as a service
88303
Configuring the analyzer to run as a service will ensure that the tool will run as soon as possible even upon the boot up of an instance. This will increase the chances of identifying services making IMDSv1 calls even as early as the instance is inited onto a network.
89304

90305
A shell script has been provided in the package that will automate the process of setting up the analyzer tool as a service. **Note:** the script/service will only work if the structure of the package is left unchanged.
91306

92307
Run the script from the command line as follows:
308+
93309
```
94310
sudo ./activate-tracer-service.sh
95311
```
96312

97-
you might need to change the file permissions with:
313+
or
314+
315+
```
316+
sudo bash activate-tracer-service.sh
317+
```
318+
319+
The permissions for the shell script may need to be changed using:
98320
```
99-
chmod 777 activate-tracer-service.sh
321+
chmod +x activate-tracer-service.sh
100322
```
101323

102-
### Deactivating the tool as a service
324+
## Deactivating the tool as a service
103325
When the tool is configured as a service using the previous script a service file is added into the OS. In order to restore the system run the script from the command line:
326+
104327
```
105328
sudo ./deactivate-tracer-service.sh
106329
```
330+
331+
or
332+
333+
```
334+
sudo bash deactivate-tracer-service.sh
335+
```
336+
107337
Permissions for the script may need to be changed:
108338
```
109-
chmod 777 deactivate-tracer-service.sh
339+
chmod +x deactivate-tracer-service.sh
110340
```
111341

342+
---
343+
112344
## Limitations
113345
We are aware of some limitations with the current version of the ImdsPacketAnalyzer. Contributions are welcomed.
114346
- The `install-deps.sh` script assumes AL2 and internet connectivity

‎activate-tracer-service.sh

+1-1
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ echo "[Service]" >> $bpf_trace_systemd_path
2929
echo "Type=simple" >> $bpf_trace_systemd_path
3030
echo "Restart=always" >> $bpf_trace_systemd_path
3131
echo "WorkingDirectory=$bpf_trace_path" >> $bpf_trace_systemd_path
32-
echo "ExecStart=/bin/python3 $bpf_trace_path/src/imds_snoop.py" >> $bpf_trace_systemd_path
32+
echo "ExecStart=$(command -v python3) $bpf_trace_path/src/imds_snoop.py" >> $bpf_trace_systemd_path
3333

3434
echo "" >> $bpf_trace_systemd_path
3535
echo "[Install]" >> $bpf_trace_systemd_path

0 commit comments

Comments
 (0)