ASIMOV Signal Module

ASIMOV module for importing Signal chats.

✨ Features

• Accesses Signal Desktop chat/contact metadata and outputs it as JSON-LD.
• Reads the encrypted Signal Desktop database on macOS, Windows, Linux, etc.
• Constructs a semantic knowledge graph based on the KNOW ontology.
• Loads environment variables from .env (aka dotenv) files.
• Distributed as a standalone static binary with zero runtime dependencies.

🛠️ Prerequisites

• Rust 1.85+ (2024 edition) if building from source code

⬇️ Installation

Installation with the ASIMOV CLI

asimov module install signal -v

Installation from Source Code

cargo install asimov-signal-module

👉 Examples

Metadata Export from Signal Desktop

Listing all private and group chats

asimov-signal-reader | jq

Listing only private chats

asimov-signal-reader | fgrep SignalChat | jq

Listing only group chats

asimov-signal-reader | fgrep SignalGroupChat | jq

Examining a specific group chat

asimov-signal-reader | fgrep "My Group Chat" | jq

Collecting all phone numbers

asimov-signal-reader | jq '.peer.phone // empty'

⚙ Configuration

Signal Desktop stores data in an encrypted SQLCipher database. The encryption key for this database is stored in a config.json file in Signal's application data directory, and that key is itself encrypted using an encryption password stored in the (platform-specific) system keychain.

This module can be configured to decrypt the Signal database using either the encryption password or the encryption key. (You don't need both, just one.)

Encryption Password

The simplest way to configure the module is to set the ASIMOV_SIGNAL_PASSWORD environment variable to the encryption password stored in the system keychain:

# macOS
export ASIMOV_SIGNAL_PASSWORD=$(security find-generic-password -a "Signal Key" -s "Signal Safe Storage" -w)

# GNOME
export ASIMOV_SIGNAL_PASSWORD=$(secret-tool lookup application Signal)

# KDE
export ASIMOV_SIGNAL_PASSWORD=$(kwallet-query kdewallet -f "Chromium Keys" -r "Chromium Safe Storage")

Encryption Key

Alternatively, for advanced users, you could set the ASIMOV_SIGNAL_KEY environment variable to the actual decrypted value of encryptedKey found in the config.json file:

export ASIMOV_SIGNAL_KEY=feedc0dedecafbadcafebabecafed00dfeedc0dedecafbadcafebabecafed00d

This key must be 64 hexadecimal characters, meaning 32 bytes (256 bits). Deriving this key manually is well beyond the scope of these instructions here.

📚 Reference

Installed Binaries

• asimov-signal-reader: reads chats from the Signal data directory

asimov-signal-reader

asimov-signal-reader

Usage: asimov-signal-reader [OPTIONS] [SIGNAL-DIR]

Arguments:
  [SIGNAL-DIR]  Path to the Signal data directory

Options:
  -d, --debug            Enable debugging output
      --license          Show license information
  -v, --verbose...       Enable verbose output (may be repeated for more verbosity)
  -V, --version          Print version information
  -o, --output <FORMAT>  Set the output format [default: jsonl] [possible values: jsonl]
  -h, --help             Print help

👨‍💻 Development

git clone https://github.com/asimov-modules/asimov-signal-module.git