first version of the knowledge base :)

20 - Knowledge/security/gpg-basics.md

@@ -0,0 +1,120 @@
+---
+title: GPG Basics
+description: Overview of core GnuPG concepts, key management, and common operational workflows
+tags:
+  - security
+  - gpg
+  - encryption
+category: security
+created: 2026-03-14
+updated: 2026-03-14
+---
+
+# GPG Basics
+
+## Introduction
+
+GPG, implemented by GnuPG, is used for public-key encryption, signing, and verification. It remains common for signing Git commits and tags, exchanging encrypted files, and maintaining long-term personal or team keys.
+
+## Purpose
+
+This document covers:
+
+- What GPG keys and subkeys are
+- Common encryption and signing workflows
+- Key management practices that matter operationally
+
+## Architecture Overview
+
+A practical GPG setup often includes:
+
+- Primary key: used mainly for certification and identity management
+- Subkeys: used for signing, encryption, or authentication
+- Revocation certificate: lets you invalidate a lost or compromised key
+- Public key distribution: keyserver, WKD, or direct sharing
+
+The primary key should be treated as more sensitive than everyday-use subkeys.
+
+## Core Workflows
+
+### Generate a key
+
+Interactive generation:
+
+```bash
+gpg --full-generate-key
+```
+
+List keys:
+
+```bash
+gpg --list-secret-keys --keyid-format=long
+```
+
+### Export the public key
+
+```bash
+gpg --armor --export KEYID
+```
+
+### Encrypt a file for a recipient
+
+```bash
+gpg --encrypt --recipient KEYID secrets.txt
+```
+
+### Sign a file
+
+```bash
+gpg --detach-sign --armor release.tar.gz
+```
+
+### Verify a signature
+
+```bash
+gpg --verify release.tar.gz.asc release.tar.gz
+```
+
+## Configuration Example
+
+Export a revocation certificate after key creation:
+
+```bash
+gpg --output revoke-KEYID.asc --gen-revoke KEYID
+```
+
+Store that revocation certificate offline in a secure location.
+
+## Troubleshooting Tips
+
+### Encryption works but trust warnings appear
+
+- Confirm you imported the correct public key
+- Verify fingerprints out of band before marking a key as trusted
+- Do not treat keyserver availability as proof of identity
+
+### Git signing fails
+
+- Check that Git points to the expected key ID
+- Confirm the GPG agent is running
+- Verify terminal pinentry integration on the local system
+
+### Lost laptop or corrupted keyring
+
+- Restore from secure backups
+- Revoke compromised keys if needed
+- Reissue or rotate subkeys while keeping identity documentation current
+
+## Best Practices
+
+- Keep the primary key offline when practical and use subkeys day to day
+- Generate and safely store a revocation certificate immediately
+- Verify key fingerprints through a trusted secondary channel
+- Back up secret keys securely before relying on them operationally
+- Use GPG where it fits existing tooling; do not force it into workflows that are better served by simpler modern tools
+
+## References
+
+- [GnuPG Documentation](https://www.gnupg.org/documentation/)
+- [The GNU Privacy Handbook](https://www.gnupg.org/gph/en/manual/book1.html)
+- [GnuPG manual](https://www.gnupg.org/documentation/manuals/gnupg/)

20 - Knowledge/security/identity-and-authentication.md

@@ -0,0 +1,65 @@
+---
+title: Identity and Authentication
+description: Core concepts and patterns for identity, authentication, and authorization in self-hosted systems
+tags:
+  - security
+  - identity
+  - authentication
+category: security
+created: 2026-03-14
+updated: 2026-03-14
+---
+
+# Identity and Authentication
+
+## Summary
+
+Identity and authentication define who or what is requesting access and how that claim is verified. In self-hosted environments, a clear identity model is essential for secure remote access, service-to-service trust, and administrative control.
+
+## Why it matters
+
+As environments grow, per-application local accounts become hard to manage and harder to audit. Shared identity patterns reduce duplicated credentials, improve MFA coverage, and make access revocation more predictable.
+
+## Core concepts
+
+- Identity: the user, service, or device being represented
+- Authentication: proving that identity
+- Authorization: deciding what the identity may do
+- Federation: delegating identity verification to a trusted provider
+- MFA: requiring more than one authentication factor
+
+## Practical usage
+
+Common self-hosted patterns include:
+
+- Central identity provider for user login
+- SSO using OIDC or SAML for web applications
+- SSH keys or hardware-backed credentials for administrative access
+- Service accounts with narrowly scoped machine credentials
+
+Example pattern:
+
+```text
+User -> Identity provider -> OIDC token -> Reverse proxy or application
+Admin -> VPN -> SSH key or hardware-backed credential -> Server
+```
+
+## Best practices
+
+- Centralize user identity where possible
+- Enforce MFA for admin and internet-facing accounts
+- Separate human accounts from machine identities
+- Review how account disablement or key rotation propagates across services
+
+## Pitfalls
+
+- Leaving critical systems on isolated local accounts with no lifecycle control
+- Reusing the same credentials across multiple services
+- Treating authentication and authorization as the same problem
+- Forgetting account recovery and break-glass access paths
+
+## References
+
+- [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html)
+- [NIST Digital Identity Guidelines](https://pages.nist.gov/800-63-3/)
+- [Yubico developer documentation](https://developers.yubico.com/)

20 - Knowledge/security/secrets-management.md

@@ -0,0 +1,109 @@
+---
+title: Secrets Management
+description: Principles and tool choices for handling secrets safely in self-hosted and engineering environments
+tags:
+  - security
+  - secrets
+  - devops
+category: security
+created: 2026-03-14
+updated: 2026-03-14
+---
+
+# Secrets Management
+
+## Introduction
+
+Secrets management is the practice of storing, distributing, rotating, and auditing sensitive values such as API tokens, database passwords, SSH private keys, and certificate material.
+
+## Purpose
+
+Good secrets management helps you:
+
+- Keep credentials out of Git and chat logs
+- Reduce accidental disclosure in deployment pipelines
+- Rotate credentials without rewriting every system by hand
+- Apply least privilege to applications and operators
+
+## Architecture Overview
+
+A practical secrets strategy distinguishes between:
+
+- Human secrets: admin credentials, recovery codes, hardware token backups
+- Machine secrets: database passwords, API tokens, TLS private keys
+- Dynamic secrets: short-lived credentials issued on demand
+- Encrypted configuration: secrets stored in version control in encrypted form
+
+Common tooling patterns:
+
+- Vault for centrally managed and dynamic secrets
+- SOPS for Git-managed encrypted secret files
+- Platform-native secret stores for specific runtimes
+
+## Operational Model
+
+### Centralized secret service
+
+A service such as Vault handles storage, access policy, audit logging, and secret issuance. This is most useful when you need rotation, leasing, or many consumers across multiple environments.
+
+### Encrypted files in Git
+
+Tools such as SOPS allow you to keep encrypted configuration alongside deployment code. This is useful for small teams and GitOps-style workflows, as long as decryption keys are managed carefully.
+
+### Runtime injection
+
+Applications should receive secrets at runtime through a controlled delivery path rather than through hard-coded values inside images or repositories.
+
+## Configuration Example
+
+Example placeholder environment file layout:
+
+```text
+APP_DATABASE_URL=postgres://app:${DB_PASSWORD}@db.internal.example/app
+APP_SMTP_PASSWORD=<provided-at-runtime>
+```
+
+Example SOPS-managed YAML structure:
+
+```yaml
+database:
+  user: app
+  password: ENC[AES256_GCM,data:...,type:str]
+smtp:
+  password: ENC[AES256_GCM,data:...,type:str]
+```
+
+## Troubleshooting Tips
+
+### Secret appears in logs or shell history
+
+- Remove it from the source immediately if exposure is ongoing
+- Rotate the credential instead of assuming it stayed private
+- Review the delivery path that leaked it
+
+### Encrypted config exists but deployments still fail
+
+- Verify the deployment environment has access to the correct decryption keys
+- Check whether placeholders or environment interpolation are incomplete
+- Confirm the application reads secrets from the documented location
+
+### Secret sprawl grows over time
+
+- Inventory where secrets live and who owns them
+- Standardize naming and rotation intervals
+- Remove stale credentials from old hosts and repos
+
+## Best Practices
+
+- Never commit plaintext secrets to Git
+- Prefer short-lived or scoped credentials where the platform supports them
+- Separate secret storage from application images
+- Rotate credentials after incidents, staff changes, and major platform migrations
+- Document ownership, rotation method, and recovery path for every critical secret
+
+## References
+
+- [HashiCorp Vault: What is Vault?](https://developer.hashicorp.com/vault/docs/what-is-vault)
+- [HashiCorp Vault documentation](https://developer.hashicorp.com/vault/docs)
+- [SOPS documentation](https://getsops.io/docs/)
+- [The Twelve-Factor App: Config](https://12factor.net/config)