The why and how of Apeeper: The EC2 Meta-data token.


Every EC2 instance exposes metadata of the running instance on its special adress: "". This service is often queried by attackers who gain a shell on a compromised host, or through application style proxy attacks.

This token has 2 design goals:

1) It installs painlessly on your EC2 host;

2) It alerts you when the meta-data service is queried.


1) In your Canary console, select the EC2 Meta-data token.

You will first be creating a token-factory. (This will allow you to mint tokens for your EC2 instances without giving them your API key or other sensitive info)

2) Choose a memo for the Apeeper Url Factory (like the EC2 region you are deploying to) and enter the number of Canarytokens you want this Factory to be able to mint. (Leaving it blank lets you create an unlimited number of tokens from this factory):

3) You will see the Apeeper Factory Url tile populated in your Canarytokens list.

At this point you have two options for finishing the deployment of the Apeeper Canarytoken.


1) Click on the "Copy Factory URL" link and head over to your running EC2 instance.

2) On your EC2 instance, update and install the necessary packages by, yum update -y && yum install python python-pip gcc -y 3) Now install the Apeeper application using pip by, pip install apeeper 4) You can run apeeper by using the Factory Url you were provided (on your Canary Console) apeeperd -a <factory_url>


1) On your console, click on the "Display AWS Startup Script". You will see a small bash script.

2) Head over to your AWS EC2 management console and start the process of launching a new instance. Stop once you get to the "Configure Instance Details" section.

3) Under "Advanced Details", you can supply the instance with "User data". If you supply it with a script, it will be run the first time it boots. Let's copy the script from our Canary console into that "User data" section. Please be wary to customise the script as need (i.e. you may want to remove the whitelisting/blacklisting flags or add paths for those options).

4) And click "Review and Launch" and launch the instance.

You now have Apeeper successfully running on your EC2 instance. You can check this by running, ps aux | grep gunicorn and checking that you can see the following two processes:

Or we can go and trigger an alert to make sure it is working correctly. Head back over to your EC2 instance and run the following command, curl -kis ""

Back on your Canary Console, you should see an alert coming through.

Whitelisting & Blacklisting ?

  • Apeeper has three modes: whitelisting, blacklisting and all. What does this mean?

Typical output from a request for metadata will look like this:

Now, you can tell apeeper to alert only if certain of those paths are queried (blacklisting) apeeperd -a <factory_url> -b /latest/meta-data/

Or you can tell apeeper to not alert for certain paths (whitelisting) apeeperd -a <factory_url> -w /latest/meta-data/

Or you can tell apeeper to alert for all paths (default) apeeperd -a <factory_url>

  • Both sets of paths can be comma separated lists.