Awesome Core

🔥 Awesome Core

一言で言うと

GitHub の awesome リストをすべてあなたのディスク上の 1 つのディレクトリに集め、 名前、言語、システム、トピックでツールをすばやく検索できます。 しかも、完全にオフラインで使えます。

たとえば、「Windows で動く OSINT 用の何か」を探しているとします。次のように入力します。

./awesome search osint --os windows

すると、複数の awesome リストからツールがまとめて表示され、 複数のリストで独立したキュレーターが選んだものが上位になるように並べ替えられます （有名な 1 つのリストに載っているものだけではありません）。

フィルターは AND で結合されるため、すぐに条件が絞り込まれます。 --os windows --lang PowerShell を指定すると、「osint」の結果は1 つだけになります。それも、探していたものではなく、 たまたま「Sherlock」という名前でもある PowerShell スクリプトです。プログラムは フィルターの条件が厳しすぎることを認識し、どの条件を外せばよいかを明示します。

注意：2 つの AND フィルターにより、結果が 1 件になりました。
    lang=PowerShell を外すと  →  結果は 8 件

原則：結果が数件より多い場合にだけ、フィルターを追加してください。

時間がない場合 — 3 つのコマンド

./awesome start      # 1. wszystko robi za Ciebie (pobiera, buduje, gotowe)
./awesome search nmap
./awesome web        # i otwiera przeglądarkę

./awesome start は、各ステップで何をしているのか、どれくらい時間がかかるのかを知らせます。 バックグラウンドで勝手に処理されることはなく、常に進捗を確認できます。

始める前に必要なもの

必要なのは 1 つだけ：Python 3.8 以降です。 以上です。

jq、curl、GitHub CLI、手動での python -m venv は不要です。

• リストのダウンロードには通常の HTTPS（core/api.py）を使います。gh がない場合は GitHub の検索が毎分 10 回に制限されるため遅くなりますが、動作します。
• Web UI 用の Flask は、最初に ./awesome web を実行したときに自動でインストールされます。
• 不足しているものがあれば、プログラムが知らせます（./awesome doctor）。

gh があり、ログインしている（gh auth login）場合、すべてが 30 倍速くなり、enrich も利用できるようになります。ただし、これは高速化のためのものであり、必須ではありません。

Linux へのインストール：

sudo apt install python3               # albo: sudo dnf install python3

オプション：ダウンロードとツールのメタデータ取得を 30 倍速くする場合：

gh auth login                          # GitHub CLI, jednorazowo

Windows では Bash は不要です。 ディレクトリには awesome.cmd があるため、PowerShell を使う場合も、ダブルクリックする場合も、次のように入力するだけです。

awesome.cmd start
awesome.cmd web

download.sh は残っていますが、現在は Python を呼び出すだけのラッパーです。中には jq も curl もシェルのループもありません。

PowerShell でのほかのコマンド：

gh auth login                 # potem reszta jak w Linuxie
.\venv\Scripts\Activate.ps1 # aktywacja venv
.\awesome web

Web UI 用の Flask は、最初に ./awesome web を実行したときに自動でインストールされます。

Web UI potrzebuje Flaska. Przygotowuję środowisko (requirements.txt):
  Tworzę venv…
  Aktualizuję pip…
  Instaluję z requirements.txt…
  Gotowe. Od teraz web używa venv/.

何らかの理由でインストールできなかった場合（ネットワークがない、プロキシなど）、プログラムが手動での手順を表示します。ただし、普段から覚えておく必要はありません。

SQL の知識、プログラミング、内部設定、自動更新は必要ありません。動作しない場合は、./awesome status が何を実行すればよいか正確に知らせます。

初回起動の手順

./awesome start

プログラムは必要なものがすべて揃っているか確認し、その後、次の処理を行います。

データベースがすでに構築されている場合、start は何も再ダウンロードしません。
ツールの数を表示して、すぐにインターフェースを起動します。再構築するには、明示的な操作が必要です。

./awesome start --rebuild    # kasuje bazę i buduje od nowa (~2 min)
./awesome refresh            # dociąga brakujące dane i przebudowuje

これなら、うっかり ./awesome start を実行しても、2 分の作業が無駄になりません。

正直にお伝えします。 start はツール自体のリポジトリを GitHub に問い合わせません。ランキングはすぐに利用できます（キュレーターの同意に基づきます）が、ツールの横に表示されるスター数は、現時点ではリスト上の推定値であり、実際の数ではありません。コマンドを 1 つ実行すれば解決します。

./awesome enrich      # 30–60 min, odpytuje ~35 tys. repozytoriów
./awesome build       # ~2 min, żeby gwiazdki wsiąkły do rankingu

または、最初から 1 つのコマンドで実行できます。

./awesome start --full   # download → build → backfill → enrich → build

これは一度実行すれば十分です。いつでも中断できます（Ctrl+C）。進捗は保存され、コマンドをもう一度実行すると続きから再開します。GitHub にログインしていない場合、enrich は処理したふりをせず、理由を説明して実行を拒否します。

時間があまりない場合は、手順 1 を省略して、後から実行できます。

./awesome start --skip-download     # szybka ścieżka: buduje z tego, co już jest

日常的な使い方

./awesome search "port scanner"                    # szukaj po ludzku
./awesome search osint --lang Python              # ...tylko Python
./awesome search "active directory" --os windows  # ...tylko pod Windowsa
./awesome langs                                    # co jest w bazie (języki)
./awesome platforms                                # systemy: Windows, Linux, Docker...
./awesome domains                                  # tematy: osint, security, network...
./awesome why nmap                                 # skąd ten wynik — punkt po punkcie
./awesome mentions nmap                            # w ilu listach jest to narzędzie
./awesome audit                                    # czy katalog nie jest zatruty fałszywymi listami
./awesome audit sindresorhus/awesome               # audyt jednego repozytorium
./awesome lists                                    # najlepsze listy
./awesome info nmap                                # dane + komenda instalacji
./awesome install nmap                             # zainstaluj (git clone)

自分用のリスト

何かを見つけて、うまく動いたら、すぐに自分用のリストに追加して、最後に生成された Markdown を貼り付けます。

./awesome shortlist add nmap --note "do skanowania sieci"
./awesome shortlist                            # co jest na liście
./awesome shortlist emit --title "Moja lista OSINT" --group domain
./awesome shortlist emit --out moja-lista.md  # zapisz do pliku

Web UI でも同じことができます。ツールのページにある ☆ 自分のリストに追加 ボタン、メニューの 自分のリスト リンクから開けるリストと Markdown を利用できます。TUI では k キーを使います。

これとは別に watch があります。これは、追跡したいリストのリポジトリ（お気に入りのリストに新しいツールが追加されていないか確認するため）の一覧であり、ツールの一覧ではありません。

./awesome watch add sindresorhus/awesome
./awesome watch check          # co doszło od ostatniego sprawdzenia

どちらのリストもローカルに保存され、バックグラウンドで自動的に問い合わせることはありません。

TUI — キー操作

/  szukaj              l  następny język      o  następna platforma
d  następna domena      s  zmień sortowanie     a  wyczyść filtry
g  ukryte perełki      u  niedoceniane        Enter  szczegóły
k  do mojej listy      i  instaluj             ?  pomoc
q  wyjście

4 つのインターフェース、同じカタログ

./awesome            # terminal — najszybszy do szybkiego szukania
./awesome tui        # terminal, ale interaktywnie (strzałki, filtry)
./awesome web        # przeglądarka (port wypisuje na ekranie)
./awesome help       # wszystkie komendy

日々のメンテナンス（自動実行される処理はありません）

./awesome status     # co jest w bazie, kiedy ostatnio odświeżone, czego brakuje
./awesome refresh    # pobierz nowe listy → metadane → przebuduj bazę

更新後、./awesome status は正確なコマンドを提案します（例：./awesome enrich）。ブラウザーでも同じ情報を確認できます。/refresh ページに 4 つのボタンがあります。cron も、デーモンも、バックグラウンドプロセスもありません。

数を確認するときの重要な注意点： ステータスに表示されるのは「スターのないツールの数」ではなく、問い合わせが必要なリポジトリの数です。これは大きな違いです。複数のツールが同じリポジトリを指すことがよくあり、GitHub 以外へのリンク（記事、動画、ドキュメント）にはスター数がなく、今後も付きません。未処理の作業として数えないでください。

収録内容

最新の数はいつでも ./awesome status で確認できます。

正直にお伝えします。 ここには AI は一切ありません。言語モデルがツールを選んだり、評価したり、ランキングしたりすることはありません。GitHub リストの README を解析し、データをそのまま集計する普通の Python プログラムです。README の数とデータベースの数が異なる場合は、誰かが STAN ブロックを更新し忘れています。./awesome status を実行して修正してください。

AI エージェント（MCP）を接続 — ローカルで、API キー不要

カタログは、ローカルのエージェント（Claude、Cursor、「Model Context Protocol」に対応したものなら何でも）にツールのソースとして提供できます。エージェントは、1 つの README に最も頻繁に記載されているかどうかではなく、独立したキュレーターの合意に基づくランキングを利用できます。

./awesome mcp --demo    # podgląd: zobaczysz całą wymianę JSON-RPC bez agenta
./awesome mcp           # serwer czeka na stdin (tak to działa w praktyce)

サーバーは 5 つのツールを提供します。search_tools（フィルターを使った検索）、 find_undiscovered_tools（過小評価されている隠れた逸品）、explain_tool （ランキングの根拠：どのリストに掲載されているか、ポイント数、評価に影響した要素）、 lists_with_tool（すべてのリストと、重複としてマークされたもの）、 catalog_facets（データベースに含まれるもの：言語、プラットフォーム、ドメイン）。

これをクライアントの設定に記述します。例：claude_desktop_config.json：

{
  "mcpServers": {
    "awesome-core": {
      "command": "/pełna/ścieżka/do/awesome-core/awesome",
      "args": ["mcp"]
    }
  }
}

または、クローンせずに PyPI から直接利用できます（パッケージ awesome-core。公式 MCP レジストリにも io.github.twojlogin/awesome-core として登録されています）。

{
  "mcpServers": {
    "awesome-core": {
      "command": "uvx",
      "args": ["awesome-core"],
      "env": { "AWESOME_DATA_DIR": "/pełna/ścieżka/do/awesome-core/data" }
    }
  }
}

uvx が PyPI からサーバーをダウンロードして起動します。AWESOME_DATA_DIR は、./awesome start で構築したデータベースのディレクトリを指定する必要があります。パッケージ自体にデータは含まれていません（データベースは約 194 MB で、ダウンロードのたびに大きくなります）。

知っておくとよいこと：

• ネットワークにデータが送信されることはありません。 API キーもアカウントも不要で、ローカルの SQLite データベースを読み取るだけです。サーバーには副作用のあるツールはありません。
• すぐに起動します — データベースはすでに構築済みで、サーバーは読み取るだけです。
• 結果は数値（スター数、独立したリストの数、スコア）を含む通常のテキストなので、エージェントは引用や比較ができます。
• プロトコルは stdin/stdout 経由の純粋な JSON-RPC 2.0 です。ログは stderr に出力され、通信チャネルを妨げません。

すべての出どころ — そして危険性について

誰もが考えるべき問いは、悪意のあるリストが投稿されたらどうなるのか？ です。

リストの出どころ： download.sh は GitHub の公開 API に、topic:awesome-list が付いたリポジトリを問い合わせます（--wide モードでは topic:awesome と topic:curated-list も対象）。スター数順に並べます。それ以外は何も行いません。「おすすめ」リポジトリも、無作為なアドレスもありません。

外部リポジトリの内容が実行されることはありません：

• README はデータです。パーサーは正規表現でリンクを抽出するだけです。README の内容が eval、exec、shell=True や、いずれかのシステム呼び出しに渡されることはありません。
• awesome install が実行するのは、正確には git clone --depth 1 です。Git はリモートリポジトリのコードを実行しません（フックも実行されません）。
• ブラウザーは HTML をエスケープし、core/md.py の Markdown レンダラーも同様にエスケープします。説明内の <script> はタグではなくテキストとして表示されます。

唯一現実的な攻撃経路：モデルのコンテキストに入る説明です。 MCP サーバーはツールの説明を、エージェントが読むテキストに変換します。その説明は、未確認のリポジトリに書かれたもので、作者も不明です。そのため：

• 説明は core/untrusted.py を通して処理されます。命令のように見える指示、ロールマーカー（system:、assistant:）、HTML タグ、curl … | sh、rm -rf を取り除き、代わりに [odfiltrowano: …] マーカーを残して、検出できるようにします。
• MCP の initialize は、これは第三者のコンテンツであり、命令ではないとエージェントに明示します。
• 必要なら自分で確認できます：

./awesome untrusted

現在の状況：186 861 個のツールで攻撃の検出数は 0 件です（3 件の検出は誤検知です — rimraf の説明に「like rm -rf」とあり、safety-net は rm -rf をブロックするツールです）。興味深い皮肉として、カタログにはまさにこの問題を防ぐツールが 3 つ含まれています（nvidia/skillspector、vaporif/parry-guard、safety-net）。

保証できないこと： スキャナーは既知のパターンを検出しますが、安全性を証明するものではありません。そのため、説明は命令ではなくデータとして扱ってください。

原則：AI を使わないコア

プロジェクトの所有者は MCP を許可しましたが、あらゆる場所に人工知能を使うことは望んでいません。特に、ローカルで動作するはずだったツールには使いたくありません。見張っていなければ、最初のリファクタリングでこの約束は消えてしまうため、ここに記しておきます。

ここから、ほかの方針も決まります。

• 外部依存は flask（ウェブ UI）のみです。コアは純粋な stdlib です。
• ランキングにモデル、埋め込み、ニューラルネットワーク、LLM は一切使いません。 並べ替えは明示的な計算式（core/scoring.py）で行うため、内容を確認して異議を唱えられます。
• ランキングはサードパーティーのサービスに依存しません。 誰かに検索結果を操作されたり、何を検索したかを知られたりすることはありません。
• MCP は境界部分のアダプターであり、コアのロジックではありません。 削除しても、何も動かなくなることはありません。
• テスト test_no_ai_in_core がこれを機械的に監視します。コアでは、許可なく AI ライブラリやネットワーク関連モジュールをインポートできません。また、MCP プロトコルを認識するファイルは core/mcp.py のみです。

カタログは汚染されるのか、そしてどう対処するのか

このカタログは他者のリポジトリから作られています。つまり、誰かが意図的に、入力を収集する偽のリストを登録し、その「ツール」から偽装ドメインや悪意のあるコードへ誘導する可能性があります。実際に起きたことはあるのでしょうか？

./awesome audit

本日時点（2026年10月6日、1 032 個のリスト、186 861 個のツール）：確認する価値のあるリストが 7 個、疑わしいリンクが 1 個です。確認された攻撃はありません。

検出するシグナルは次のとおりです。

データベースで見つかった例：laoma2053/awesome-zhuiju-free — ツール 25 個、スター 0 個、説明なし。リンクはどれも、ほかのリストによって確認されていません。

行っていないこと、そしてそれを知っておくべき理由：

• これはマルウェアスキャナーではありません。 リポジトリ内のドロッパーや、ツールのコードに含まれる悪意のあるコードは検出しません。すべてを見逃さないとは約束できません。
• シグナルは断定ではありません。 フラグは「手動で確認する」という意味であり、「悪意がある」という意味ではありません。検出された 7 件のうち 3 件は、誠実ではあるものの、風変わりなリストでした。
• ランキングはすでに対策を講じています：ツールが承認されるには、少なくとも 2 つの独立したリストからの承認が必要です。また、リストのコピーはその承認数に含まれません。新しい偽リストが 1 つできても、何かが上位に押し上げられることはありません。
• awesome install は単なる git clone です。 スクリプトを実行せず、GitHub のパスワードを尋ねず、リモートリポジトリのコードを実行することもありません。ただし、その後、そのコードをどう扱うかを決めるのはあなた自身です。プログラムはそこまで管理しません。
• ほかのリストの説明は MCP を通じてモデルのコンテキストに入るため、core/untrusted.py で処理されます（セキュリティのセクションを参照）。

最も簡単なルール：新しいリスト 1 つだけに載っていて、聞いたこともないツールは、インストールを勧めるものではなく、確認が必要なサインです。

分からない用語 — 用語集

このプログラムは何も推薦しません。「おすすめ」「最良の選択肢」といった表現も、ツールを提案する LLM もありません。あるのは、数値化された情報（独立したキュレーターの合意、スター数、リストの品質、ツールが掲載されているリスト）と、基準が明示されたフィルターです。選ぶのはあなたです。プログラムが示すすべての情報は、数値で確認できます。 | バックフィル | 不足しているリストのメタデータを取得することです | | エンリッチ | ツールのリポジトリを確認することです（API への問い合わせ1回につき、50件をまとめて処理します） | | ビルド | ローカルの README ファイルからデータベースを再構築することです（約2分） | | ファセット | クリックできるサイドフィルターです（例：「言語：Python」） |

ライセンス

MIT — ディレクトリ内の LICENSE をご覧ください。コードは私のものですが、ツールの名前、リンク、短い説明は他者の awesome list に由来し、それぞれの作成者に帰属します。データベースにはリポジトリの URL と名前のみが含まれています（事実であり、他者のコンテンツではありません）。README 自体はリポジトリに含まれていません。./download.sh を使って、自分のディスクにダウンロードしてください。

既知の制限事項（正直に）

ランキングが読み取るのは作成者が書いた内容であり、コードではありません。名前、説明、スター数、トピック、README は、どれも自由に記述でき、すべてスコアに反映されます。このプログラムはリポジトリのコードを確認しないため、同じ名前のスクリプト集とツールを区別できず、オリジナルとコピーも見分けられません。

測定可能な結果として、awesome selfcheck は既知のツール15件をチェックし（名前 → 正しいリポジトリ）、通常は 13/15件で1位になります。失敗する2件では、常に同じ仕組みが働いています。ツール名を説明に繰り返し記載したファン作成のリポジトリが、オリジナルより上位になります。

./awesome selfcheck

これはこのアプローチの限界であり、重みを調整しても解決できません。乗り越えるには、リポジトリの内容（インポート、入力ファイル、リリースタグ）を確認する必要がありますが、それは別のプロジェクトです。私は意図的に、その確認をしているかのようには装いません。

それほど重大ではありませんが、こちらも明記しておきます：

• ツールの91%は1つのリストにしか掲載されていないため、「キュレーターの合意」はゼロです。この考え方が有効なのはカタログの大部分であり、少数の部分ではありません
• 75 571件の項目は GitHub 以外へのリンク（記事、動画、ドキュメント）です。スター数は取得できず、ツールでもありません

• GitHub の検索では、1回のクエリにつき最大1000件の結果しか返されません。 そのため、ダウンロードでは複数のクエリを同時に使用し（--wide）、結果を拡張します。
• ツールの実際の言語が分かるのは、./awesome enrich で確認したリポジトリに限られます。ほかは URL と説明から推測するため、不明な場合は ? と表示されます。ランキングでは、意図的にこの推測を信用しません。
• GitHub 以外へのリンクを確認するのは、要求があった場合のみです： ./awesome validate --non-github --limit 500
• **ツールの安全性は確認しません。**リポジトリに付くシグナル（アーカイブ済み、長期間更新されていないなど）は確認のための手掛かりであり、評価ラベルではありません。インストールする前に、コードとリリースを確認してください。

さらに詳しく知りたい方へ

awesome              # wygodny wrapper: ./awesome <komenda>
download.sh          # pobieranie README list z GitHuba (bash + gh + jq)
extract_tools.py     # budowa bazy z lokalnych README
data/awesome.db      # baza SQLite (generowana, w .gitignore)
offline-db/          # pobrane README list (generowane, w .gitignore)

core/store.py        # schemat bazy, migracje, zapis metadanych
core/parser.py       # wyciąganie narzędzi z markdown (listy i tabele)
core/langmap.py      # język / platforma / domena / czyszczenie URL-i
core/scoring.py      # consensus, jakość listy, ranking
core/aliases.py      # synonimy („port scanner” → nmap, masscan…)
core/md.py           # własny renderer Markdown → HTML (bez CDN)
core/builder.py      # orkiestracja builda
core/backfill.py     # metadane list
core/enrich.py       # metadane repozytoriów narzędzi
core/status.py       # stan danych i plan odświeżenia
core/tools_db.py     # zapytania (search, fasetki, ranking)
core/database.py     # zapytania po listach/repozytoriach
core/curator.py      # kolekcje + instalacja
core/validator.py    # weryfikacja linków
core/trust.py        # sygnały ryzyka przy repozytoriach
cli/awesome_cli.py   # CLI
cli/tui.py           # TUI (curses)
web/app.py           # Flask UI
web/templates/       # szablony Jinja2
tests/smoke_test.py  # 106 testy (CI)

mcp-name: io.github.twojlogin/awesome-core