Keylogme Zero

This is a logger for keylogme.com . This logger saves the stats locally. You can use those results to visualize in (pending...).

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Security
2. Getting Started
   • Linux
3. Config
   • USB name
   • Keycodes hardware
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgments

About The Project

The end goal is to avoid or diminish the pain in your hands due to typing. Commonly known as RSI (Repetitive Strain Injury), tennis elbow, carpal tunnel syndrome, etc.

There are many great ergonomic keyboards , beautiful hardware out there. However, what is the layout of keys that best suits you? that does not cause you pain? that makes you more productive?.

We all started with QWERTY, then heard of DVORAK, COLEMAK, Workman, Norman, Asset, Capewell-Dvorak, BEAKL, MTGAP, QGMLWB... ? There are many layouts but switching to one is not an easy task, you need a lot of practice and patience.

Here's how:

• Monitor : See the finger usage on your layout based on your real usage
• Analyze : Compare your layout with others, find patterns to avoid or improve, remap shortcuts
• Adapt : fine tune your layout based on the stats

Of course, ergonomics is not just a nice keyboard and layout. It is also about posture, breaks, exercises.

(back to top)

Security

A keylogger is a tool that records the keystrokes on a computer. It can be used for good or bad purposes. Of course, our intention is to use it for good purposes. How can you trust that?, well the code is completely open source, no dependencies and it stores your data locally in your computer, there is no connection to the internet.

The online viewer does not need an account to use it. You can use it anonymously to visualize your stats.

Getting Started

Linux

1. Clone the repo

   git clone https://github.com/keylogme/keylogme-zero.git

2. Go to deploy and install with sudo permissions

   cd deploy && sudo ./install.sh

   With parameters

   If you want to install a specific version: ```sh cd deploy && sudo ./install.sh v1.1.0 ``` If you want to install and use your own config (don't forget the version, in this case latest): ```sh cd deploy && sudo ./install.sh latest /absolute/path/to/your/config.json ```

3. After some keypresses and 10 seconds, check the stats in /output_keylogme_zero.json

(back to top)

Config

The file deploy/default_config.json contains the default config. You can use it as a template to create your own config.:

{
    "keylog": {
        "devices": [
            {
                "device_id": "1",
                "name": "⌨️✋ crkbd",
                "usb_name": "foostan Corne"
            }
        ],
        "shortcut_groups": [
            {
                "id": "A",
                "name": "Clipboard ✏️",
                "shortcuts": [
                    {
                        "id": "1A",
                        "name": "Copy 📎",
                        "codes": [
                            29,
                            46
                        ],
                        "type": "hold"
                    }
                ]
            },
            {
                "id": "B",
                "name": "Nvim 🕶️",
                "shortcuts": [
                    {
                        "id": "1B",
                        "name": "Save 💾",
                        "codes": [
                            57,
                            31
                        ],
                        "type": "seq"
                    }
                ]
            }
        ]
    },
    "storage": {
        "file_output": "output_keylogme_zero.json",
        "periodic_save_in_sec": 10
    }
}

The config has two main sections:

• keylog : config for keylogger
  • devices : list of devices to monitor
    • device_id : unique id for the device
    • name : name of the device, you named it as you want.
    • usb_name : usb name of the device. Go to USB name section to know how to get it.
  • shortcuts : list of shortcuts to monitor
    • id : unique id for the shortcut
    • codes : list of keycodes (decimal format) for the shortcut. Go to Keycodes hardware section to know how to get it.
    • type : type of shortcut. There are two: hold for holding shortcuts like copy (CTRL+C) and seq for sequential shortcuts like used in (neo)vim for shortcuts.
• storage : config for storage
  • file_output : abs filepath to store the stats
  • periodic_save_in_sec : periodic time to save the stats. In seconds.

(back to top)

USB name

A usb device connected to computer has a unique name. To get the name of the device, you can use the following command:

apt install input-utils
sudo lsinput

If your keyboard name appeared multiple times, try with all of them.

For example, the output of the command for my corne keyboard is below and the name that worked is foostan Corne.

Output lsinput related to keyboard

/dev/input/event12
   bustype : BUS_USB
   vendor  : 0x4653
   product : 0x1
   version : 273
   name    : "foostan Corne"
   phys    : "usb-0000:00:14.0-4.3/input0"
   uniq    : ""
   bits ev : (null) (null) (null) (null) (null)

/dev/input/event13
   bustype : BUS_USB
   vendor  : 0x4653
   product : 0x1
   version : 273
   name    : "foostan Corne System Control"
   phys    : "usb-0000:00:14.0-4.3/input2"
   uniq    : ""
   bits ev : (null) (null) (null) (null)

/dev/input/event14
   bustype : BUS_USB
   vendor  : 0x4653
   product : 0x1
   version : 273
   name    : "foostan Corne Consumer Control"
   phys    : "usb-0000:00:14.0-4.3/input2"
   uniq    : ""
   bits ev : (null) (null) (null) (null) (null)

/dev/input/event15
   bustype : BUS_USB
   vendor  : 0x4653
   product : 0x1
   version : 273
   name    : "foostan Corne Keyboard"
   phys    : "usb-0000:00:14.0-4.3/input2"
   uniq    : ""
   bits ev : (null) (null) (null) (null) (null)

Keycodes hardware

A key (hardware) has a keycode, f.e. in a normal QWERTY keyboard, the keycode of Q is 10(HEX) and 16(Decimal), letter C is 2E(HEX) and 46(Decimal).

The keyboard (hardware) sends the keycode to the computer. The computer uses the keyboard layout to convert the keycode to a character. The keyboard layout is defined in your operating system. For example, the layout US QWERTY will convert 16(Decimal) to Q and 46(Decimal) to C. But if I have defined another layout, for example WORKMAN, then keycode 16(Decimal) will be Q and 46(Decimal) will be M. You get the idea 🙃

How to know the keycode? Go to kbdlayout.info and click scancodes to see the keycodes. The scancode is a hex number, you have to convert it to decimal.

Roadmap

• Keylog multiple devices
• Handle connection/disconnection of devices
• Handle shortcuts
  • Hold shortcuts: like copy (Ctrl+C)
  • Sequential shortcuts: like used in (neo)vim for shortcuts
• Local storage of stats
• Installation script and keylogger compatible with
  • Linux
  • Windows
  • Mac
• Performance WPM
• Accuracy

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Contact

Efrain Sotelo - @esoteloferry

Project Link: https://keylogme.com

(back to top)

Acknowledgments

Helpful resources and would like to give credit to.

• Linux keylogger helpful starting point

(back to top)