test3

---

name: KeePassXC Integration description: Integracja KeePassXC z Cursorem do bezpiecznego zarządzania sekretami (hasła, tokeny API, klucze SSH) compatibility: - wsl - windows

---

Skill: KeePassXC Integration

KeePassXC is a local password manager: it stores entries (Title, Username, Password, URL, Notes) in an encrypted .kdbx database. There is no cloud API; the database is a single file. Access is via GUI or keepassxc-cli.

Activation Gate

Użyj tego skill gdy:

Użytkownik potrzebuje pobrać sekret z bazy KeePassXC (hasło, token API, klucz SSH)

Użytkownik chce użyć keepassxc-cli do zarządzania sekretami

Użytkownik pyta o konfigurację KeePassXC z Cursorem

Before implementing KeePassXC features, verify architecture:

Keyring (SecretManagement/secret-tool) = database password ONLY

KeePassXC database = ALL secrets (passwords, tokens, keys)

No file-based fallbacks

Przegląd

Ten skill umożliwia bezpieczne zarządzanie sekretami przez KeePassXC z poziomu Cursora. Używa osobnej bazy cursor.kdbx z hasłem przechowywanym w PowerShell SecretManagement, SSH Agent dla kluczy SSH, oraz keepassxc-cli dla innych sekretów.

Struktura danych w bazie

Grupy: używaj hierarchii {project_name}/{env_name} (np. myapp/prod, myapp/dev). Ścieżka wpisu w CLI to np. ProjectName/EnvName/EntryTitle.

Wpisy: pole Title = nazwa sekretu (np. "GitHub Token", "API Key"); pole Password = wartość sekretu. Dla API key trzymaj wartość w Password, opcjonalnie Username = "api".

Po co: spójna struktura umożliwia check-before-add (unikanie duplikatów) i skrypty oparte na ścieżce.

Konfiguracja

Zmienne środowiskowe

KEEPASS_DB_PATH - ścieżka do bazy Cursor (ustawiona w ~/.profile i ~/.bashrc)

- WSL: /mnt/c/Users/janja/OneDrive/Dokumenty/Inne/cursor.kdbx - Windows: C:\Users\janja\OneDrive\Dokumenty\Inne\cursor.kdbx

Hasło bazy

Hasło bazy jest przechowywane w:

PowerShell SecretManagement (główna metoda, pozwala na odczyt, dostępne z Windows i WSL)

secret-tool (opcjonalny fallback dla WSL, jeśli D-Bus dostępny)

Windows Credential Manager (backup, tylko zapis, nie można odczytać programatycznie)

WAŻNE:

SecretManagement/secret-tool przechowują TYLKO hasło bazy KeePassXC, nie hasła z bazy

Wszystkie sekrety (hasła, tokeny API, klucze SSH) są przechowywane wyłącznie w bazie KeePassXC

Nie ma fallbacku do pliku - wszystkie metody używają bezpiecznych mechanizmów keyring

Hasło jest automatycznie zapisywane przez skrypt save-keepass-password-to-keyring.sh gdy baza jest otwarta w GUI.

Użycie

Podstawowe komendy

#### Pobieranie sekretu przez skrypt pomocniczy

# Pobierz hasło z wpisu
~/.cursor/scripts/get-keepass-secret.sh "Entry Title" "Password"
Pobierz token API
~/.cursor/scripts/get-keepass-secret.sh "GitHub Token" "Token"
Pobierz dowolny atrybut
~/.cursor/scripts/get-keepass-secret.sh "Entry Title" "Attribute Name"

#### Bezpośrednie użycie keepassxc-cli

# Lista wszystkich wpisów
keepassxc-cli ls "$KEEPASS_DB_PATH"
Wyświetl szczegóły wpisu
keepassxc-cli show "$KEEPASS_DB_PATH" "Entry Title"
Pobierz konkretny atrybut
keepassxc-cli show -a "Password" "$KEEPASS_DB_PATH" "Entry Title"
Pobierz hasło (interaktywnie, jeśli nie jest w SecretManagement)
echo "hasło" | keepassxc-cli show -a "Password" "$KEEPASS_DB_PATH" "Entry Title"

Zapisywanie hasła do keyring

# Uruchom skrypt (wymaga otwartej bazy w GUI)
~/.cursor/scripts/save-keepass-password-to-keyring.sh

Dodawanie i aktualizacja wpisów

Obowiązkowy workflow przed zapisem (check-before-add): Zawsze sprawdź, czy grupa i wpis istnieją; nie dodawaj duplikatu.

1. Sprawdzenie: keepassxc-cli ls "$KEEPASS_DB_PATH" "ProjectName/EnvName" (ew. -R) lub keepassxc-cli locate "$KEEPASS_DB_PATH" "EntryTitle" — czy wpis już jest? 2. Jeśli wpis istnieje → użyj edit, nie add: keepassxc-cli edit "$KEEPASS_DB_PATH" "ProjectName/EnvName/EntryTitle" (opcje -t, -u, --url, -p/-g dla hasła). 3. Jeśli brak grupy → najpierw mkdir: keepassxc-cli mkdir "$KEEPASS_DB_PATH" "ProjectName/EnvName". 4. Jeśli wpisu nie ma → add: keepassxc-cli add "$KEEPASS_DB_PATH" "ProjectName/EnvName/EntryTitle" z -u username, --url (opcjonalnie), -p (prompt hasła) lub -g (generuj hasło).

Komendy keepassxc-cli: add, edit, show, ls, locate, mkdir, rm. Ograniczenia: w wielu wersjach CLI add i edit nie obsługują custom attributes ani Notes; tylko Title, Username, URL, Password.

Scenariusze:

Odczyt: istniejący skrypt get-keepass-secret lub keepassxc-cli show (ścieżka lub tytuł wpisu).

Zapis nowego sekretu: check (ls/locate) → mkdir grupy jeśli brak → add wpisu.

Aktualizacja sekretu: locate/show → edit (zmiana hasła/username).

Inicjalizacja struktury: mkdir ProjectName, mkdir ProjectName/EnvName.

Skrypty Pythona: Po wdrożeniu użyj scripts/keepass_ops.py (subkomendy get/add/update) dla spójnego check-before-add; szczegóły w doc/keepass-integration.md. Dla zaawansowanych przypadków nadal możesz wywoływać keepassxc-cli bezpośrednio.

SSH Agent

KeePassXC SSH Agent automatycznie ładuje klucze SSH z bazy do systemowego SSH agenta gdy baza jest otwarta w GUI.

Weryfikacja

# W PowerShell (Windows)
ssh-add -l
Powinien być widoczny klucz SSH z bazy

Użycie kluczy SSH

Klucze SSH są automatycznie dostępne dla wszystkich połączeń SSH (nie trzeba podawać -i).

Przykłady użycia

Pobieranie tokenu GitHub

GITHUB_TOKEN=$(~/.cursor/scripts/get-keepass-secret.sh "GitHub Token" "Token")
export GITHUB_TOKEN

Pobieranie hasła do bazy danych

DB_PASSWORD=$(~/.cursor/scripts/get-keepass-secret.sh "Database Credentials" "Password")

Pobieranie klucza API

API_KEY=$(~/.cursor/scripts/get-keepass-secret.sh "Service API" "API Key")

Bezpieczeństwo

Best Practices

1. Nie commituj haseł do Git - wszystkie sekrety są w bazie KeePassXC 2. Używaj SSH Agent - klucze SSH są automatycznie ładowane, nie przechowywane na dysku 3. Hasło w SecretManagement - bezpieczniejsze niż w zmiennych systemowych lub plikach 4. Osobna baza Cursor - izolacja sekretów Cursora od głównej bazy 5. Regularna synchronizacja - używaj KeeShare lub Merge do synchronizacji z główną bazą 6. Tylko hasło bazy w keyring - wszystkie inne sekrety są wyłącznie w bazie KeePassXC

Ostrzeżenia

Hasło bazy jest przechowywane w PowerShell SecretManagement - dostępne tylko dla użytkownika

Skrypt get-keepass-secret.sh próbuje w kolejności:

1. PowerShell SecretManagement (główna metoda) 2. secret-tool (jeśli dostępny w WSL) 3. Wpis w bazie "Cursor Database Password" (jeśli baza otwarta w GUI) 4. Interaktywnie (ostatni fallback)

Baza musi być otwarta w GUI, aby odczytać hasło z wpisu "Cursor Database Password"

Nie ma fallbacku do pliku - wszystkie metody używają bezpiecznych mechanizmów keyring

Rozwiązywanie problemów

Problem: "Nie można odczytać hasła z bazy"

Rozwiązanie: 1. Upewnij się, że baza cursor.kdbx jest otwarta w KeePassXC GUI 2. Sprawdź czy wpis "Cursor Database Password" istnieje w bazie 3. Uruchom save-keepass-password-to-keyring.sh aby zapisać hasło do SecretManagement

Problem: "keepassxc-cli: command not found"

Rozwiązanie:

sudo apt update
sudo apt install -y keepassxc

Problem: "Cannot retrieve secret from SecretManagement"

Rozwiązanie: 1. Sprawdź czy moduły są zainstalowane:

   Get-Module -ListAvailable -Name Microsoft.PowerShell.SecretManagement
   

2. Jeśli nie, zainstaluj:

   Install-Module -Name Microsoft.PowerShell.SecretManagement -Scope CurrentUser
   Install-Module -Name Microsoft.PowerShell.SecretStore -Scope CurrentUser
   

3. Zarejestruj vault:

   Register-SecretVault -Name LocalStore -ModuleName Microsoft.PowerShell.SecretStore -DefaultVault
   

Problem: Klucze SSH nie są widoczne w ssh-add

Rozwiązanie: 1. Upewnij się, że SSH Agent jest włączony w KeePassXC (Tools → Settings → SSH Agent) 2. Upewnij się, że Windows OpenSSH Agent jest uruchomiony:

   Set-Service ssh-agent -StartupType Automatic
   Start-Service ssh-agent
   

3. Sprawdź czy klucz SSH jest dodany do bazy z konfiguracją SSH Agent

Synchronizacja baz

Baza cursor.kdbx może być synchronizowana z główną bazą jjaszczak.kdbx używając:

KeeShare (rekomendowane) - GUI-based synchronizacja

Merge - jednorazowe scalenie baz

Szczegółowe instrukcje w planie integracji.

Dokumentacja

Runbook (odtworzenie na innej maszynie): ~/.cursor/doc/keepass-integration.md

Plan integracji: ~/.cursor/plans/keepassxc_integration_setup_6191af80.plan.md

Konfiguracja: ~/.cursor/doc/configuration.md

Skrypty: ~/.cursor/scripts/ (get-keepass-secret.sh, save-keepass-password-to-keyring.sh, keepass_ops.py)

1. Nie commituj haseł do Git - wszystkie sekrety są w bazie KeePassXC 2. Używaj SSH Agent - klucze SSH są automatycznie ładowane, nie przechowywane na dysku 3. Hasło w SecretManagement - bezpieczniejsze niż w zmiennych systemowych lub plikach 4. Osobna baza Cursor - izolacja sekretów Cursora od głównej bazy 5. Regularna synchronizacja - używaj KeeShare lub Merge do synchronizacji z główną bazą 6. Tylko hasło bazy w keyring - wszystkie inne sekrety są wyłącznie w bazie KeePassXC

Ostrzeżenia

Hasło bazy jest przechowywane w PowerShell SecretManagement - dostępne tylko dla użytkownika

Skrypt get-keepass-secret.sh próbuje w kolejności:

1. PowerShell SecretManagement (główna metoda) 2. secret-tool (jeśli dostępny w WSL) 3. Wpis w bazie "Cursor Database Password" (jeśli baza otwarta w GUI) 4. Interaktywnie (ostatni fallback)

Baza musi być otwarta w GUI, aby odczytać hasło z wpisu "Cursor Database Password"

Nie ma fallbacku do pliku - wszystkie metody używają bezpiecznych mechanizmów keyring