leonjza/ooktools

📡 On-off keying tools for your SD-arrrR

ooktools

---

ooktools aims to help with the reverse engineering of on-off keying data sources such as wave files or raw frames captured using RfCat.

---

why?

I recently played around a little with static key remotes, and wrote some code to help with the reverse engineering thereof.

major features

• Binary string extraction from wave file recordings.
• Wave file cleanups to remove noise in On-off keying recordings.
• Graphing capabilities for wave files.
• General information extraction of wave files.
• Signal recording and playback using json definition files that can be shared.
• Plotting of data from the previously mentioned json recordings.
• Signal searching for On-off keying type data.
• Sending signals in both binary, complete PWM formatted or hex strings using an RfCat dongle.
• Gnuradio .grc template file generation.
• Signal 'jammer' by continuously sending a loud, static signal.
• Signal brute forcer that can iterate over a bitstring range.

installation

You can install ooktools in two ways. Either from pip or from source. In case of a source installation, you may want to optionally consider installing it in a virtualenv.

rfcat

In both installation cases, you need to install RfCat. This too can be done in two ways. On Kali Linux, you can install it with a simple apt command:

$ apt install rfcat

Or, if you need to manually install it, download the latest RfCat sources and run the setup.py script:

$ wget -c https://bitbucket.org/atlas0fd00m/rfcat/downloads/rfcat_150225.tgz
$ tar xjvf rfcat_150225.tgz
$ cd rfcat_150225
$ python setup.py install

ooktools

Pip Package:

$ pip install ooktools

Using this method, you should have the ooktools command available globally.

From source:

$ git clone https://github.com/leonjza/ooktools.git
$ cd ooktools
$ pip install -r requirements.txt

If you installed from source then you can invoke ooktools with as a module using python -m ooktools.console from the directory you cloned to.

usage

There are a number of sub commands that are grouped by major category. At anytime, add the --help argument to get a full description of any other sub commands and or arguments available.

$ ooktools --help
         _   _           _
 ___ ___| |_| |_ ___ ___| |___
| . | . | '_|  _| . | . | |_ -|
|___|___|_,_|_| |___|___|_|___| v0.1
On-off keying tools for your SD-arrrR
https://github.com/leonjza/ooktools

Usage: ooktools [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  gnuradio  GNU Radio Commands.
  signal    Signal Commands.
  wave      Wave File Commands.

For full examples, please refer to the blogpost here

known issues

Nothing is perfect I guess. One of the biggest problems would be test cases and variations. So, here is the stuff that I know is not 100% perfect. Pull requests welcome!

• Wave file operations such as graph and clean break when the wave file is too long. ~50M samples seem to start hitting the point of breakage.
• The matplotlib usage is silly from a performance perspective. Its the main reason I don't have live graphs in too as I just cant get it working great.

license

Please refer to the LICENSE file.

ooktools's Issues

TypeError: sequence item 0: expected str instance, bytes found

ooktools wave clean --source ~/gqrx_20220327.wav -D test

Total Samples: 39563, Min: -16699, Max: 16701, Mean: 1.0
Cleaning up 39563 data points...
Normalizing values..
Writing output to file: test

Traceback (most recent call last):
[...]
  File "/usr/lib/python3/dist-packages/click/core.py", line 555, in invoke
    return callback(*args, **kwargs)
  File "/home/yug/.local/lib/python3.8/site-packages/ooktools/console.py", line 103, in clean
    converstions.clean_pwm_wave(**locals())
  File "/home/yug/.local/lib/python3.8/site-packages/ooktools/commands/converstions.py", line 75, in clean_pwm_wave
    output_wave.writeframes(''.join(frames))

ooktools v1.4, Python 3.8.10

Feature request: support for RFQuack on EvilCrowRF

I think the EvilCrowRF hardware is interesting as it allows for full duplex with two modems and the RFQuack firmware would be supportive for complex tools such as OOK tools.

EvilcrowRF: it is even much cheaper than YARDstick One.
https://github.com/joelsernamoreno/EvilCrow-RF

RFQuack:
https://github.com/rfquack/RFQuack

Are you still interested in such gadgets and use cases? It would be great to also support RFquack in OOK tools.

not work on python 2.7 and python 3.8

Traceback (most recent call last):
File "/usr/lib/python2.7/runpy.py", line 174, in _run_module_as_main
"main", fname, loader, pkg_name)
File "/usr/lib/python2.7/runpy.py", line 72, in _run_code
exec code in run_globals
File "/usr/local/lib/python2.7/dist-packages/ooktools/console.py", line 30, in
from .commands import information
File "/usr/local/lib/python2.7/dist-packages/ooktools/commands/information.py", line 33, in
numpy.set_printoptions(threshold=numpy.nan)
File "/usr/lib/python2.7/dist-packages/numpy/core/arrayprint.py", line 246, in set_printoptions
floatmode, legacy)
File "/usr/lib/python2.7/dist-packages/numpy/core/arrayprint.py", line 93, in _make_options_dict
raise ValueError("threshold must be numeric and non-NAN, try "
ValueError: threshold must be numeric and non-NAN, try sys.maxsize for untruncated representation

NameError: name 'xrange' is not defined

hi folks,
thxx for this great tool, just a note, facing an issue on kali, first install, no issues but when i run it
sudo ooktools signal record --frequency 433920000 --framecount 60 --destination bell.json

i get

┌──(nocomp㉿R3dB0x)-[~/tools/sdr/ooktools]
└─$ sudo ooktools signal record --frequency 433920000 --framecount 60 --destination bell.json 130 ⨯
_ _ _
___ | || | ___ | |
| . | . | '| | . | . | | -|
|||,|| ||||___| v1.4
On-off keying tools for your SD-arrrR
https://github.com/leonjza/ooktools

Recording on frequency: 433920000 to /home/nocomp/tools/sdr/ooktools/bell.json
Configuring Radio
[radio] Frequency: 433920000
[radio] MdmModulation: 48
[radio] PktFLEN: 0
[radio] MdmDRate: 38400
[radio] MdmSyncMode: 0
[radio] Lowball: True
For maximum frames, press and release the remote multiple times.
Traceback (most recent call last):
File "/usr/local/bin/ooktools", line 8, in
sys.exit(cli())
File "/usr/lib/python3/dist-packages/click/core.py", line 829, in call
return self.main(*args, **kwargs)
File "/usr/lib/python3/dist-packages/click/core.py", line 782, in main
rv = self.invoke(ctx)
File "/usr/lib/python3/dist-packages/click/core.py", line 1259, in invoke
return _process_result(sub_ctx.command.invoke(sub_ctx))
File "/usr/lib/python3/dist-packages/click/core.py", line 1259, in invoke
return _process_result(sub_ctx.command.invoke(sub_ctx))
File "/usr/lib/python3/dist-packages/click/core.py", line 1066, in invoke
return ctx.invoke(self.callback, **ctx.params)
File "/usr/lib/python3/dist-packages/click/core.py", line 610, in invoke
return callback(*args, **kwargs)
File "/usr/local/lib/python3.9/dist-packages/ooktools/console.py", line 166, in record
signalling.record(**locals())
File "/usr/local/lib/python3.9/dist-packages/ooktools/commands/signalling.py", line 190, in record
for c in xrange(0, framecount):
NameError: name 'xrange' is not defined
===== RESETUP set from recv thread
python3: ../../libusb/os/threads_posix.h:46: usbi_mutex_lock: Assertion `pthread_mutex_lock(mutex) == 0' failed.
zsh: abort sudo ooktools signal record --frequency 433920000 --framecount 60 bell.json

any idea about what can be wrong?

thxx for your support