thinkst/opencanary低リソースで動作するハニーポット。一般的なネットワークサービスをエミュレートして侵害後の攻撃者活動を検出し、拡張可能なプロトコルモジュールと設定可能なアラートを備えています。
OpenCanary はマルチプロトコル対応のネットワークハニーポットです。主なユースケースは、攻撃者が非公開ネットワークに侵入した後に検知することです。リソース要件が非常に低く、調整・変更・拡張が可能です。
OpenCanary はデーモンとして動作し、複数の一般的なネットワークプロトコルを実装しています。攻撃者がネットワークに侵入してハニーポットとやり取りすると、OpenCanary はさまざまな仕組みでアラートを送信します。
OpenCanary は Python で実装されているため、コアのハニーポットはクロスプラットフォームですが、一部の機能は特定の OS を必要とします。Linux で実行すると最も多くのオプションを利用できます。リソース要件は非常に低く、たとえば Raspberry Pi や最小限のリソースの VM でも問題なく稼働できます。
この README では、Ubuntu Linux と MacOS での OpenCanary のインストールおよび設定方法について説明します。
OpenCanary は、商用の Thinkst Canary ハニーポットのオープンソース版です。
OpenCanary のインストールは、基本的に Python 環境を準備してから、OpenCanary Python パッケージ（およびオプションの追加パッケージ）をインストールするという流れです。
uv がインストールされている場合は、仮想環境の作成とパッケージのインストールにそれを使用できます。インストールされていない場合は、以下の標準的な python/pip の手順が引き続き機能します。
Ubuntu 22.04 LTS または 24.04 LTS へのインストール:
$ sudo apt-get install python3-dev python3-pip python3-virtualenv python3-venv python3-scapy libssl-dev libpcap-dev
$ virtualenv env/
$ . env/bin/activate
$ pip install opencanary
オプション: uv を使用する場合:
$ uv venv env
$ . env/bin/activate
$ uv pip install opencanary
オプションの追加パッケージ（Windows ファイル共有モジュールと SNMP モジュールを使用する場合）:
$ sudo apt install samba # if you plan to use the Windows File Share module
$ pip install scapy pcapy-ng # if you plan to use the SNMP module
まず、新しい Python 仮想環境を作成してアクティベートします:
$ virtualenv env/
$ . env/bin/activate
オプション: uv を使用する場合:
$ uv venv env
$ . env/bin/activate
Macports ユーザーは次を実行してください:
$ sudo port install openssl
$ env ARCHFLAGS="-arch x86_64" LDFLAGS="-L/opt/local/lib" CFLAGS="-I/opt/local/include" pip install cryptography
または、Homebrew x86 ユーザーは次を実行してください:
$ brew install openssl
$ env ARCHFLAGS="-arch x86_64" LDFLAGS="-L/usr/local/opt/openssl/lib" CFLAGS="-I/usr/local/opt/openssl/include" pip install cryptography
Homebrew M1 ユーザーは次を実行してください:
$ brew install openssl
$ env ARCHFLAGS="-arch arm64" LDFLAGS="-L/opt/homebrew/opt/[email protected]/lib" CFLAGS="-I/opt/homebrew/opt/[email protected]/include" pip install cryptography
(上記のコンパイル手順は、複数の OpenSSL バージョンが存在する可能性があり、Python ライブラリを混乱させる可能性があるため必要です。)
これで、通常どおりインストールを実行できます:
$ pip install opencanary
$ pip install scapy pcapy-ng # optional
uv がインストールされている場合、同等のコマンドは次のとおりです:
$ uv pip install opencanary
$ uv pip install scapy pcapy-ng # optional
Windows ファイル共有（smb）モジュールは macOS では利用できません。
pip を実行する代わりにソースからインストールするには、次の手順を実行します:
$ git clone https://github.com/thinkst/opencanary
$ cd opencanary
$ python setup.py sdist
$ cd dist
$ pip install opencanary-<version>.tar.gz
uv がインストールされている場合、最後のインストール手順を次に置き換えることができます:
$ uv pip install opencanary-<version>.tar.gz
OpenCanary は pkgx を介してパッケージ化されているため、pkgx がインストールされていればインストールは不要で、opencanaryd コマンドの前に
pkgx を付けるだけです。最新の sudo 実装における環境変数保護のため、コマンド全体を root として実行するか、sudo -E を使用して実行する必要があります。
$ pkgx opencanaryd --version
OpenCanary の Docker イメージは Docker Hub でホストされています。正確なネットワーク情報を得るには host ネットワークエンジンが必要なため、これらのイメージは Linux の Docker ホストでのみ役立ちます。
OpenCanary は起動時に以下の場所で設定ファイルを探し、最初に見つかった設定で停止します。
/etc/opencanaryd/opencanary.conf~/.opencanary.conf（つまりユーザーのホームディレクトリ。通常は root なので /root/.opencanary.conf）./opencanary.conf（つまり OpenCanary がインストールされているディレクトリ）初期設定を作成するには、root として実行します（sudo パスワードを求められる場合があります）:
$ opencanaryd --copyconfig
[*] A sample config file is ready /etc/opencanaryd/opencanary.conf
[*] Edit your configuration, then launch with "opencanaryd --start --uid=nobody --gid=nogroup"
これにより、パスとファイル /etc/opencanaryd/opencanary.conf が作成されます。次に、設定ファイルを編集して、有効にするサービスとログオプションを決定する必要があります。
[!WARNING] 設定ファイルには複雑なデータが含まれており、ログ設定用の Python オブジェクトが含まれています。設定は、プロセスが root 権限で実行されている間に読み取られます。ファイルを root が所有し、root のみが書き込み可能にすることをお勧めします。通常のユーザーがファイルに書き込める場合、root への権限昇格が可能になる可能性があります。
設定は JSON 設定ファイルを介して行います。ファイルを編集し、問題がなければ保存して終了します。
snmp モジュールは、Scapy が存在する場合にのみ利用できます。上記の SNMP のインストール手順を参照してください。
portscan モジュールは iptables ルールを変更するため、Linux ホストでのみ利用できます。
Portscan サービスについては、portscan.ignore_localhost 設定を追加したことに注意してください。これは、OpenCanary の portscan サービスが localhost IP（127.0.0.1）からのポートスキャンを無視する（アラートを出さない）ことを意味します。この設定はデフォルトで false です。
Windows ファイル共有モジュール（smb）には Samba のインストールが必要です。Wiki でステップバイステップのガイドを参照してください。
OpenCanary は、Linux または macOS ホスト上で直接実行するか、Docker コンテナを介して実行します。
次のコマンドを実行して OpenCanary を起動します:
$ . env/bin/activate
$ opencanaryd --start --uid=nobody --gid=nogroup
uid フラグと gid フラグを使用すると、OpenCanary はポートにバインドした後に root 権限を放棄します。これは他の低権限ユーザー/グループに変更したり、省略して root 権限のまま実行し続けたりすることもできます。
次のコマンドを実行して OpenCanary を起動します:
$ sudo -E pkgx opencanaryd --start --uid=nobody --gid=nogroup
uid フラグと gid フラグを使用すると、OpenCanary はポートにバインドした後に root 権限を放棄します。これは他の低権限ユーザー/グループに変更したり、省略して root 権限のまま実行し続けたりすることもできます。
この方法では、Docker と Docker Compose がインストールされている必要があります。
Note Docker 化された OpenCanary では、portscan モジュールは自動的に無効になります。
data/.opencanary.conf ファイルを編集します。docker-compose.yml ファイルの ports セクションを編集します。docker compose up latest
ログを表示するには、docker compose logs latest を実行します。
コンテナを停止するには、docker compose down を実行します。
docker compose を使用して独自の Docker OpenCanary を構築するには、wiki をご覧ください。
Docker 化された OpenCanary の詳細については、専用の Docker wiki をご覧ください。
Ansible OpenCanary ロールについては、フォークしたリポジトリをこちらで参照してください。
このプロジェクトへの PR を歓迎します。プルリクエストを送信する前に、行動規範とコントリビュートのドキュメントをお読みください。
PR を送信する前に、少なくとも pre-commit を実行してください。OpenCanary がインストールされている Python 環境と同じ環境にインストールして実行します:
$ pip install pre-commit
$ pre-commit install
# Do work
$ git add file
$ git commit
# If pre-commit generated errors, then run "git add ... && git commit" again
セキュリティ脆弱性の報告方法の詳細については、セキュリティポリシーを参照してください。
提供しているテンプレートを使用して、Github にバグ報告を登録してください。
機能リクエストはこちらで追跡されています。
このプロジェクトと、それに参加するすべての人は、 行動規範によって管理されています。 参加することにより、この規範を遵守することが期待されます。受け入れがたい行為は [email protected] まで報告してください。