<p align="center"> <img src="img/kb_logo.png?raw=true" width="200"/> </p>

kb. A minimalist knowledge base manager

Author: gnc nebbionegiuseppe@gmail.com

Copyright: © 2020, gnc

Date: 2025-06-22

Version: 0.1.8

Table of Contents

• Purpose
• Installation
  • Installation from AUR
  • Installation from pkgsrc
  • Installation with homebrew
  • Notes for Windows users
• Docker
• Usage
  • List artifacts
    • List all artifacts contained in the kb knowledge base
    • List all artifacts containing the string "zip"
    • List all artifacts belonging to the category "cheatsheet"
    • List all the artifacts having the tags "web" or "pentest"
    • List using "verbose mode"
  • Add artifacts
    • Add a file to the collection of artifacts
    • Add a file to the artifacts
    • Add all files contained in a directory to kb
    • Create a new artifact from scratch
    • Create a new artifact from the output of another program
  • Delete artifacts
    • Delete an artifact by ID
    • Delete multiple artifacts by ID
    • Delete an artifact by name
  • View artifacts
    • View an artifact by id
    • View an artifact by name
    • View an artifact without colors
    • View an artifact within a text-editor
  • Edit artifacts
    • Edit an artifact by id
    • Edit an artifact by name
  • Grep through artifacts
    • Grep through the knowledge base
    • Grep (case-insensitive) through the knowledge base
    • Grep in "verbose mode" through the knowledge base
    • Grep through the knowledge base and show matching lines
  • Import/Export/Erase a knowledge base
    • Export the current knowledge base
    • Import a knowledge base
    • Erase the entire knowledge base
  • Manage Templates
    • List available templates
    • Create a new template
    • Delete a template
    • Edit a template
    • Add a template
    • Change template for an artifact
    • Apply a template to all artifacts of a category
    • Apply a template to all artifacts having zip in their title
    • Apply a template to all artifacts having specific properties
  • Integrating kb with other tools
    • kb and rofi
  • Experimental
    • Synchronize kb with a remote git repository
• UPGRADE
• FAQ
• DONATIONS
• COPYRIGHT

Purpose

kb is a text-oriented minimalist command line knowledge base manager. kb can be considered a quick note collection and access tool oriented toward software developers, penetration testers, hackers, students or whoever has to collect and organize notes in a clean way. Although kb is mainly targeted on text-based note collection, it supports non-text files as well (e.g., images, pdf, videos and others).

The project was born from the frustration of trying to find a good way to quickly access my notes, procedures, cheatsheets and lists (e.g., payloads) but at the same time, keeping them organized. This is particularly useful for any kind of student. I use it in the context of penetration testing to organize pentesting procedures, cheatsheets, payloads, guides and notes.

I found myself too frequently spending time trying to search for that particular payload list quickly, or spending too much time trying to find a specific guide/cheatsheet for a needed tool. kb tries to solve this problem by providing you a quick and intuitive way to access knowledge.

In few words kb allows a user to quickly and efficiently:

• collect items containing notes,guides,procedures,cheatsheets into an organized knowledge base;
• filter the knowledge base on different metadata: title, category, tags and others;
• visualize items within the knowledge base with (or without) syntax highlighting;
• grep through the knowledge base using regexes;
• import/export an entire knowledge base;

Basically, kb provides a clean text-based way to organize your knowledge.

Installation

You should have Python 3.6 or above installed.

To install the most recent stable version of kb just type:

pip install -U kb-manager

If you want to install the bleeding-edge version of kb (that may have some bugs) you should do:

git clone https://github.com/gnebbia/kb
cd kb
pip install -r requirements.txt
python setup.py install

# or with pip
pip install -U git+https://github.com/gnebbia/kb

Tip for GNU/Linux and MacOS users: For a better user experience, also set the following kb bash aliases:

cat <<EOF > ~/.kb_alias
alias kbl="kb list"
alias kbe="kb edit"
alias kba="kb add"
alias kbv="kb view"
alias kbd="kb delete --id"
alias kbg="kb grep"
alias kbt="kb list --tags"
EOF
echo "source ~/.kb_alias" >> ~/.bashrc
source ~/.kb_alias

Please remember to upgrade kb frequently by doing:

pip install -U kb-manager

Installation from AUR

Arch Linux users can install kb or kb-git with their favorite AUR Helper.

Stable:

yay -S kb

Dev:

yay -S kb-git

Installation from pkgsrc

Of course it runs on NetBSD (and on pkgsrc). We can install it from pkgsrc source tree (databases/py-kb) or as a binary package using pkgin:

pkgin in py38-kb

Note that at the moment the package is only available from -current repositories.

Installation with homebrew

To install using homebrew, use:

brew tap gnebbia/kb https://github.com/gnebbia/kb.git
brew install gnebbia/kb/kb

To upgrade with homebrew:

brew update
brew upgrade gnebbia/kb/kb

Notes for Windows users

Windows users should keep in mind these things:

• DO NOT USE notepad as %EDITOR%, kb is not compatible with notepad, a reasonable alternative is notepad++;
• %EDITOR% variable should ALWAYS be enclosed within double quotes;

EDITOR=C:\Program Files\Editor\my cool editor.exe      -> WRONG!
EDITOR="C:\Program Files\Editor\my cool editor.exe"    -> OK!

To set the "EDITOR" Environment variable by using cmd.exe, just issue the following commands, after having inserted the path to your desired text editor:

set EDITOR="C:\path\to\editor\here.exe"
setx EDITOR "\"C:\path\to\editor\here.exe\""

To set the "EDITOR" Environment variable by using Powershell, just issue the following commands, after having inserted the path to your desired text editor:

$env:EDITOR='"C:\path\to\editor\here.exe"'
[System.Environment]::SetEnvironmentVariable('EDITOR','"C:\path\to\editor\here.exe"', [System.EnvironmentVariableTarget]::User)

Setting Aliases for cmd

Open a cmd.exe terminal with administrative rights and paste the following commands:

reg add "HKEY_LOCAL_MACHINE\Software\Microsoft\Command Processor" /v "AutoRun" /t REG_EXPAND_SZ /d "%USERPROFILE%\autorun.cmd"
(
echo @echo off
echo doskey kbl=kb list $*
echo doskey kbe=kb edit $*
echo doskey kba=kb add $*
echo doskey kbv=kb view $*
echo doskey kbd=kb delete --id $*
echo doskey kbg=kb grep $*
echo doskey kbt=kb list --tags $*
)> %USERPROFILE%\autorun.cmd

Setting Aliases for Powershell

Open a Powershell terminal and paste the following commands:

@'
function kbl { kb list $args }
function kbe { kb edit $args }
function kba { kb add  $args }
function kbv { kb view $args }
function kbd { kb delete --id $args }
function kbg { kb grep $args }
function kbt { kb list --tags $args }
'@ >  $env:USERPROFILE\Documents\WindowsPowerShell\profile.ps1

Docker

A docker setup has been included to help with development.

To install and start the project with docker:

docker-compose up -d
docker-compose exec kb bash

The container has the aliases included in its .bashrc so you can use kb in the running container as you would if you installed it o