Awesome Core

🔥 Awesome Core

Czym to jest, w jednym zdaniu

Ściąga wszystkie awesome listy z GitHuba do jednego katalogu na Twoim dysku i pozwala szybko znaleźć narzędzie — po nazwie, języku, systemie albo temacie — całkowicie bez internetu.

Na przykład chcesz „coś do OSINT-a działające pod Windows". Wpisujesz:

./awesome search osint --os windows

i dostajesz narzędzia z kilku różnych awesome list naraz, posortowane tak, że na górze są te, które niezależni kuratorzy wskazali w wielu listach (a nie tylko te z jednej głośnej listy).

Filtry łączy AND, więc kumulują się szybko. --os windows --lang PowerShell

zostawia z „osint" jedno narzędzie — i to nie to, czego szukałeś, tylko

skrypt PowerShell, który akurat też nazywa się „Sherlock". Program wie, że

filtr jest za wąski, i mówi wprost, który odpuścić:

`

Uwaga: 2 filtry łączy AND i zostawiły 1 wynik(ów).

bez lang=PowerShell → 8 wyników

`

Zasada: dodawaj filtr tylko wtedy, gdy wyników jest więcej niż kilka.

---

Jeśli nie masz czasu — trzy komendy

./awesome start      # 1. wszystko robi za Ciebie (pobiera, buduje, gotowe)

./awesome search nmap ./awesome web # i otwiera przeglądarkę

./awesome start mówi w każdym kroku, co robi i ile to potrwa. Nic działa się samo w tle — zawsze widzisz postęp.

---

Co musisz mieć zanim zaczniesz

Jedna rzecz: Python 3.8 lub nowszy. To wszystko.

Nie potrzebujesz jq, curl, GitHub CLI ani samodzielnego python -m venv:

• pobieranie list działa przez zwykły HTTPS (core/api.py) — bez gh jest wolniej, bo GitHub limituje wyszukiwanie do 10 zapytań na minutę, ale działa;
• Flask do web UI instaluje się sam przy pierwszym ./awesome web;
• program sam mówi, gdy brakuje czegoś (./awesome doctor).

Jeśli masz gh i się zalogujesz (gh auth login), wszystko idzie 30× szybciej i enrich w ogóle się odblokuje. Ale to przyspieszenie, nie warunek.

Instalacja na Linuksie:

sudo apt install python3               # albo: sudo dnf install python3

Opcjonalnie, dla 30× szybszego pobierania i metadanych narzędzi:

gh auth login                          # GitHub CLI, jednorazowo

Windows działa bez basha. W katalogu jest awesome.cmd, więc w PowerShellu albo po podwójnym kliknięciu piszesz po prostu:

awesome.cmd start

awesome.cmd web

download.sh został, ale to już tylko nakładka wywołująca Pythona — w nim nie ma już ani jq, ani curl, ani pętli w shellu.

W PowerShellu odpowiedniki reszty komend:

gh auth login                 # potem reszta jak w Linuxie

.\venv\Scripts\Activate.ps1 # aktywacja venv .\awesome web

Flask do web UI instaluje się sam, przy pierwszym ./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/.

Jeśli z jakiegoś powodu to się nie uda (brak sieci, proxy), program wypisze instrukcję ręczną — ale nie musisz jej pamiętać na co dzień.

Nie musisz znać SQL, programować, nic konfigurować w środku i nie musisz nic aktualizować automatycznie. Jak coś nie działa — ./awesome status powie Ci, co dokładnie odpalić.

---

Pierwsze uruchomienie, krok po kroku

./awesome start

Program sprawdza, czy masz wszystko, potem:

Jeśli baza już jest zbudowana, `start` nie pobiera nic od nowa. Wypisuje liczbę narzędzi i od razu włącza interfejs. Przebudowa wymaga świadomej decyzji:

./awesome start --rebuild    # kasuje bazę i buduje od nowa (~2 min)

./awesome refresh # dociąga brakujące dane i przebudowuje

Dzięki temu przypadkowe ./awesome start nie kasuje Ci 2 minuty pracy.

Uwaga, uczciwie: start nie odpytuje GitHuba o repozytoria samych narzędzi. Ranking od razu działa (na zgodzie kuratorów), ale gwiazdka przy narzędziu to na razie szacunek z listy, nie prawdziwa liczba. Jedna komenda to naprawia:

./awesome enrich      # 30–60 min, odpytuje ~35 tys. repozytoriów

./awesome build # ~2 min, żeby gwiazdki wsiąkły do rankingu

Albo jednym poleceniem od zera:

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

Robisz to raz. Przerwać można w każdej chwili (Ctrl+C) — postęp jest zapisywany i odpalanie komendy drugi raz jedzie dalej. Bez zalogowania do GitHuba enrich odmawia z wyjaśnieniem zamiast udawać, że zrobił swoją robotę.

Jeśli masz mało czasu, krok 1 możesz pominąć i nadrobić później:

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

Codzienne użycie

./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)

Twoja własna lista

Jak coś znajdziesz i działa — włóż to od razu na swoją listę, a na końcu wklej gotowy 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

W web UI jest to samo: przycisk ☆ Do mojej listy na stronie narzędzia, lista i Markdown pod linkiem *Moja lista* w menu. W TUI klawisz k.

Osobno istnieje watch — lista repozytoriów list, które chcesz śledzić (nowe narzędzia w ulubionej liście), a nie lista narzędzi:

./awesome watch add sindresorhus/awesome

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

Obie listy są lokalne i żadna nie odpytuje się sama w tle.

TUI — klawisze

/  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

Cztery interfejsy, ten sam katalog

./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

---

Codzienna pielęgnacja (nic nie leci samo)

./awesome status     # co jest w bazie, kiedy ostatnio odświeżone, czego brakuje

./awesome refresh # pobierz nowe listy → metadane → przebuduj bazę

./awesome status po odświeżeniu podpowiada dokładną komendę, np. ./awesome enrich. To samo w przeglądarce: strona /refresh z czterema przyciskami. Żadnych cronów, daemonów ani procesów w tle.

Ważne przy liczbach: status nie mówi „X narzędzi bez gwiazdek", tylko ile repozytoriów zostało do odpytania. Różnica jest ogromna, bo kilka narzędzi często wskazuje na to samo repo, a linki poza GitHubem (artykuły, filmy, dokumentacja) nie mają i nigdy nie będą miały gwiazdek — nie licz ich jako brakującej pracy.

---

---

Co jest w środku

Aktualne liczby zawsze sprawdzisz: ./awesome status.

---

Uczciwa uwaga: nie ma tu żadnego AI. Żadne modele językowe nie wybierają, nie oceniają ani nie rankują narzędzi. To zwykły Python, który parsuje README z list GitHuba i liczy rzeczy na surowo. Jeśli liczby w README różnią się od bazy — ktoś zapomniał odświeżyć blok STAN. Zrób ./awesome status i popraw.

Podłącz agenta AI (MCP) — lokalnie, bez kluczy API

Katalog można dać do dyspozycji lokalnemu agentowi (Claude, Cursor, cokolwiek mówi „Model Context Protocol”) jako źródło narzędzi. Agent dostaje ranking oparty o zgodę niezależnych kuratorów, a nie o to, co jest najczęściej wypisane w jednym 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)

Serwer daje 5 narzędzi: search_tools (szukanie z filtrami), find_undiscovered_tools (niedoceniane i ukryte perełki), explain_tool (uzasadnienie rankingu: z jakich list, ile punktów, co ważyło), lists_with_tool (wszystkie listy + oznaczone kopie) i catalog_facets (co jest w bazie: języki, platformy, domeny).

Wpisz to do konfiguracji klienta, np. claude_desktop_config.json:

{

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

Albo bez klonowania — prosto z PyPI (paczka awesome-core, obecna też w oficjalnym rejestrze MCP jako 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 pobierze i uruchomi serwer z PyPI. AWESOME_DATA_DIR musi wskazywać katalog z bazą zbudowaną przez ./awesome start — sama paczka nie zawiera danych (baza ma ~194 MB i rośnie z każdym pobraniem).

Co warto wiedzieć:

• Nic nie wychodzi do sieci. Zero kluczy API, zero kont, tylko odczyt lokalnej bazy SQLite. Serwer nie ma narzędzi z efektem ubocznym.
• Start jest natychmiastowy — baza jest już zbudowana, serwer tylko czyta.
• Wyniki to zwykły tekst z liczbami (gwiazdki, liczba niezależnych list, score), więc agent może je cytować i porównywać.
• Protokół jest czystym JSON-RPC 2.0 po stdin/stdout; logi idą na stderr, żeby nie psuły kanału.

---

Skąd to wszystko pochodzi — i czy mi szkodzi

Pytanie, które powinien zadać każdy: *co jeśli ktoś wrzuci złośliwą listę?*

Skąd listy: download.sh pyta publiczne API GitHuba o repozytoria oznaczone topic:awesome-list (plus topic:awesome i topic:curated-list w trybie --wide), posortowane po gwiazdkach. Nic więcej — żadnych „polecanych" repozytoriów, żadnych losowych adresów.

Nic z obcego repozytorium nigdy nie jest wykonywane:

• README jest danymi. Parser