<!-- #  -->
# audiocat
Audiocat is a command-line utility for Linux that reads and writes encrypted data across peer-to-peer or broadcast audio connections, using [minimodem](https://github.com/kamalmostafa/minimodem "minimodem") and [gpg](https://github.com/gpg/gnupg "gpg").
It is a powerful tool that can be combined with any audio infrastructure (like PSTN, cellular network, internet, radio, walkie-talkies) to provide a secure communication channel through an audio tunnel.
The audio interfaces behave like data-diodes, each allowing unidirectional data transmission only, thus preventing data-leaks and malware-injection.
This enables an "enhanced"-end-to-end encryption (E-E2EE) which notably increases security and privacy, especially when the end devices are completely offline (air-gapped-system), thus providing an effective barrier against "legal or illegal" client-side-scanning!
See also <https://www.codeproject.com/Articles/5295970/Audio-Chat-for-Quite-Good-Privacy-AC4QGP>
## Installation
```
pip install audiocat-clark
```
or with git:
```
git clone https://github.com/ClarkFieseln/audiocat.git
cd audiocat_clark
chmod +x audiocat
chmod +x *.sh
```
during first execution you will be asked to install dependencies: minimodem, gpg, bc
but you can also install them yourself with:
```
sudo apt install minimodem
sudo apt install gpg
sudo apt install bc
```
The package gnome-terminal is assumed to be already installed, install otherwise or change cfg/terminal.
## How to use (pip installation)
### Chat/Messenger
```
audiocat -c
```
enter and confirm password
On the other device a chat or a remote shell can be started.
### Remote Shell
```
audiocat -s
```
then enter and confirm password
On the other device a chat shall be started to command the remote shell.
Note that this is technically a "reverse shell" which gives access to your system!
### File Transfer
```
audiocat -f
```
enter and confirm password
On the other device a file transfer shall be started.
### Probe
To check connectivity and adjust volumes if required.
```
audiocat -p
```
In addition, a separate terminal will be opened to read unencrypted probe messages being sent by the other side.
## Configuration
Adapt the configuration as required using the 'terminal GUI' with:
```
audiocat -g
```
<!-- #  -->
Alternatively, you may change the configuration by editing the files in the cfg folder directly. The 'Location' can be found with:
```
audiocat -d
```
The most important settings are:
* baud
* keepalive_time_sec
* retransmission_timeout_sec
* split_tx_lines
* volume_microphone
* volume_speaker_left
* volume_speaker_right
Note that the communication partners may require different values as it is the case with keepalive_time_sec !
## How to use (git installation)
When installed with git, audiocat may be called with:
```
python3 audiocat.py -c
# or
./audiocat -c
```
This is an example to start a chat, but this is the same for any other option.
For more information check the [documentation](https://github.com/ClarkFieseln/audiocat/blob/main/doc/documentation.md).
## Features
on top of the audio modem provided by minimodem and encryption provided by GPG, audiocat offers a reliable transport layer and many other features:
- modes: chat, remote-shell, file transfer (future: sniffer)
- full-duplex communication
- retransmit messages automatically after communication errors
- split big messages into smaller data chunks in order to increase the probability of reception, thus reducing retransmissions
- [keepalive] messages
- redundant transmission of "data-messages"
- composition of piped commands hidden to the user
- tmp folder located in a configurable path beneath $HOME, independent of the current path.
- probe, to check volume on receiver and adjust manually if needed
(very high and very low volumes may produce signal distortions)
- "braodcast" transmissions also possible, e.g. when ACKs are deactivated
use-case: walkie-talkie, Radio station, ...
- several configuration options: preamble, trailer, delays, cipher algorithm, confidence, log to file, verbose, etc.
## Possible Abuses
please don't do the following if you are not allowed (it might be illegal!):
- exfiltrate data over the air or cable to a nearby or remote computer
- remote control over the air or cable from a nearby or remote computer
- exfiltrate data from a computer evading classical auditing
(be aware that if you do this on your employer's computer you might be infringing the law!)
- use the tool as a "side-channel" for covert communication e.g. to spread or inject malware,
even worse when combined with steganography (e.g. low volumes, data hidden in noise)
## Typical Configuration
<!-- #  -->
A: audiocat in offline PC (Alice)
D: audiocat in offline PC (Bob)
B, C: smartphone with call session (mobile, messenger app, etc.)
diodes: audio connections (sink/speaker -> source/microphone)
## Communication in Linux over Linphone
<!-- #  -->
A: audiocat in offline PC (Alice)
D: audiocat in offline PC (Bob)
B, C: smartphone with [Linphone](https://www.linphone.org) call session
## Communication in Termux over qTox
<!-- #  -->
A: audiocat in offline smartphone with Termux (Alice)
D: audiocat in offline smartphone with Termux (Bob)
B, C: PC with qTox call session
## Communication in Linux over Walkie Talkies
<!-- #  -->
## Split Configuration
<!-- #  -->
A: audiocat in offline PC (Alice)
D: audiocat in offline PC (Bob)
B1, B2, C1, C2: waklie-talkie
## Limitations
The data transfer is usually done at low rates, typical of audio systems. Therefore, this tool is not adequate to transmit big files which may take a long time to complete.
## Hints
Avoid using tools like PulseEffects, they may produce glitches!
## PyPi Project
https://pypi.org/project/audiocat-clark
## GitHub Project
https://github.com/ClarkFieseln/audiocat
## Documentation
https://github.com/ClarkFieseln/audiocat/blob/main/doc/documentation.md
## Screenshots
https://github.com/ClarkFieseln/audiocat/tree/main/screenshots
## Videos
https://www.youtube.com/playlist?list=PLX24fhcibpHUx7ej_Tp4neobJUqOkqliN
## License
(c) 2025 Clark Fieseln
This repository is licensed under the MIT license. See LICENSE for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/ClarkFieseln/audiocat",
"name": "audiocat-clark",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "chat, messenger, remote shell, remote control, reverse shell, file transfer, modem, audio, cryptography, encryption, security, cybersecurity, linux, gpg, minimodem, e2ee, data diode",
"author": "Clark Fieseln",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/98/d8/cf675c2e2f0aa3af3a274a1d4caa4eb32ae3ab42b980be4a5dd8d9ee784b/audiocat_clark-0.10.tar.gz",
"platform": null,
"description": "<!-- #  -->\n\n\n# audiocat\nAudiocat is a command-line utility for Linux that reads and writes encrypted data across peer-to-peer or broadcast audio connections, using [minimodem](https://github.com/kamalmostafa/minimodem \"minimodem\") and [gpg](https://github.com/gpg/gnupg \"gpg\").\n\nIt is a powerful tool that can be combined with any audio infrastructure (like PSTN, cellular network, internet, radio, walkie-talkies) to provide a secure communication channel through an audio tunnel.\n\nThe audio interfaces behave like data-diodes, each allowing unidirectional data transmission only, thus preventing data-leaks and malware-injection.\n\nThis enables an \"enhanced\"-end-to-end encryption (E-E2EE) which notably increases security and privacy, especially when the end devices are completely offline (air-gapped-system), thus providing an effective barrier against \"legal or illegal\" client-side-scanning!\n\nSee also <https://www.codeproject.com/Articles/5295970/Audio-Chat-for-Quite-Good-Privacy-AC4QGP>\n\n\n## Installation\n```\n pip install audiocat-clark\n```\n\n or with git:\n\n```\n git clone https://github.com/ClarkFieseln/audiocat.git\n\n cd audiocat_clark\n\n chmod +x audiocat\n\n chmod +x *.sh\n```\n \n during first execution you will be asked to install dependencies: minimodem, gpg, bc\n \n but you can also install them yourself with:\n```\n sudo apt install minimodem\n sudo apt install gpg\n sudo apt install bc\n```\n The package gnome-terminal is assumed to be already installed, install otherwise or change cfg/terminal.\n\n## How to use (pip installation)\n### Chat/Messenger\n\n```\n audiocat -c\n```\nenter and confirm password\n\nOn the other device a chat or a remote shell can be started.\n\n### Remote Shell\n\n```\n audiocat -s\n```\nthen enter and confirm password\n\nOn the other device a chat shall be started to command the remote shell.\n\nNote that this is technically a \"reverse shell\" which gives access to your system!\n\n### File Transfer\n\n```\n audiocat -f\n```\nenter and confirm password\n\nOn the other device a file transfer shall be started.\n\n### Probe\nTo check connectivity and adjust volumes if required.\n\n```\n audiocat -p\n```\n\nIn addition, a separate terminal will be opened to read unencrypted probe messages being sent by the other side.\n\n## Configuration\nAdapt the configuration as required using the 'terminal GUI' with:\n\n```\n audiocat -g\n```\n<!-- #  -->\n\n\nAlternatively, you may change the configuration by editing the files in the cfg folder directly. The 'Location' can be found with:\n\n```\n audiocat -d\n```\n\nThe most important settings are:\n\n* baud\n* keepalive_time_sec\n* retransmission_timeout_sec\n* split_tx_lines\n* volume_microphone\n* volume_speaker_left\n* volume_speaker_right\n\nNote that the communication partners may require different values as it is the case with keepalive_time_sec !\n\n## How to use (git installation)\nWhen installed with git, audiocat may be called with: \n\n```\n python3 audiocat.py -c\n # or\n ./audiocat -c\n```\nThis is an example to start a chat, but this is the same for any other option.\n\nFor more information check the [documentation](https://github.com/ClarkFieseln/audiocat/blob/main/doc/documentation.md).\n\n## Features\non top of the audio modem provided by minimodem and encryption provided by GPG, audiocat offers a reliable transport layer and many other features:\n\n- modes: chat, remote-shell, file transfer (future: sniffer)\n\n- full-duplex communication\n\n- retransmit messages automatically after communication errors\n\n- split big messages into smaller data chunks in order to increase the probability of reception, thus reducing retransmissions\n\n- [keepalive] messages\n \n- redundant transmission of \"data-messages\"\n \n- composition of piped commands hidden to the user\n\n- tmp folder located in a configurable path beneath $HOME, independent of the current path.\n\n- probe, to check volume on receiver and adjust manually if needed\n\n (very high and very low volumes may produce signal distortions)\n \n- \"braodcast\" transmissions also possible, e.g. when ACKs are deactivated\n\n use-case: walkie-talkie, Radio station, ...\n \n- several configuration options: preamble, trailer, delays, cipher algorithm, confidence, log to file, verbose, etc.\n\n## Possible Abuses\nplease don't do the following if you are not allowed (it might be illegal!):\n\n- exfiltrate data over the air or cable to a nearby or remote computer\n\n- remote control over the air or cable from a nearby or remote computer\n\n- exfiltrate data from a computer evading classical auditing\n\n (be aware that if you do this on your employer's computer you might be infringing the law!)\n \n- use the tool as a \"side-channel\" for covert communication e.g. to spread or inject malware,\n\n even worse when combined with steganography (e.g. low volumes, data hidden in noise)\n \n## Typical Configuration\n\n<!-- #  -->\n\nA: audiocat in offline PC (Alice)\n\nD: audiocat in offline PC (Bob)\n\nB, C: smartphone with call session (mobile, messenger app, etc.)\n\ndiodes: audio connections (sink/speaker -> source/microphone)\n\n## Communication in Linux over Linphone\n\n<!-- #  -->\n\n\nA: audiocat in offline PC (Alice)\n\nD: audiocat in offline PC (Bob)\n\nB, C: smartphone with [Linphone](https://www.linphone.org) call session\n\n## Communication in Termux over qTox\n\n<!-- #  -->\n\n\nA: audiocat in offline smartphone with Termux (Alice)\n\nD: audiocat in offline smartphone with Termux (Bob)\n\nB, C: PC with qTox call session\n\n## Communication in Linux over Walkie Talkies\n\n<!-- #  -->\n\n\n## Split Configuration\n\n<!-- #  -->\n\n\nA: audiocat in offline PC (Alice)\n\nD: audiocat in offline PC (Bob)\n\nB1, B2, C1, C2: waklie-talkie\n\n## Limitations\nThe data transfer is usually done at low rates, typical of audio systems. Therefore, this tool is not adequate to transmit big files which may take a long time to complete.\n\n## Hints\nAvoid using tools like PulseEffects, they may produce glitches!\n\n## PyPi Project\n\nhttps://pypi.org/project/audiocat-clark\n\n## GitHub Project\n\nhttps://github.com/ClarkFieseln/audiocat\n\n## Documentation\n\nhttps://github.com/ClarkFieseln/audiocat/blob/main/doc/documentation.md\n\n## Screenshots\n\nhttps://github.com/ClarkFieseln/audiocat/tree/main/screenshots\n\n## Videos\n\nhttps://www.youtube.com/playlist?list=PLX24fhcibpHUx7ej_Tp4neobJUqOkqliN\n\n## License\n\n(c) 2025 Clark Fieseln\n\nThis repository is licensed under the MIT license. See LICENSE for details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Encrypted audio tunnel for secure chat, file transfer and remote shell on Linux.",
"version": "0.10",
"project_urls": {
"Homepage": "https://github.com/ClarkFieseln/audiocat",
"Source": "https://github.com/ClarkFieseln/audiocat"
},
"split_keywords": [
"chat",
" messenger",
" remote shell",
" remote control",
" reverse shell",
" file transfer",
" modem",
" audio",
" cryptography",
" encryption",
" security",
" cybersecurity",
" linux",
" gpg",
" minimodem",
" e2ee",
" data diode"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "cd22cb9030678f40187f010eca17fa1f8cc7e21ab0acc50170941095a57942d2",
"md5": "2378fd51fbb1108c2da8b7e22f41ca6b",
"sha256": "8b38088baca49adf432a7a65caaf4c1058f73cdb2adcd19a1385fab2db7ff7dc"
},
"downloads": -1,
"filename": "audiocat_clark-0.10-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2378fd51fbb1108c2da8b7e22f41ca6b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 237065,
"upload_time": "2025-02-11T15:13:43",
"upload_time_iso_8601": "2025-02-11T15:13:43.424259Z",
"url": "https://files.pythonhosted.org/packages/cd/22/cb9030678f40187f010eca17fa1f8cc7e21ab0acc50170941095a57942d2/audiocat_clark-0.10-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "98d8cf675c2e2f0aa3af3a274a1d4caa4eb32ae3ab42b980be4a5dd8d9ee784b",
"md5": "3f0884e52500ca6a57443bcf58ce5436",
"sha256": "8faa46dee594531045dbd2d1aace61a81f6151f149512a6f8b789f297970ba3a"
},
"downloads": -1,
"filename": "audiocat_clark-0.10.tar.gz",
"has_sig": false,
"md5_digest": "3f0884e52500ca6a57443bcf58ce5436",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 115120,
"upload_time": "2025-02-11T15:13:45",
"upload_time_iso_8601": "2025-02-11T15:13:45.197796Z",
"url": "https://files.pythonhosted.org/packages/98/d8/cf675c2e2f0aa3af3a274a1d4caa4eb32ae3ab42b980be4a5dd8d9ee784b/audiocat_clark-0.10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-11 15:13:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ClarkFieseln",
"github_project": "audiocat",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "audiocat-clark"
}
JSON
