A minimalist command line knowledge base manager
Author: gnc nebbionegiuseppe@gmail.com
Copyright: © 2020, gnc
Date: 2022-09-21
Version: 0.1.7
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:
Basically, kb provides a clean text-based way to organize your knowledge.
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
Arch Linux users can install kb or kb-git with their favorite AUR Helper.
Stable:
yay -S kb
Dev:
yay -S kb-git
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.
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
Windows users should keep in mind these things:
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)
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
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
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 on the
host directly. The ./docker/data
directory on the host is bound to
/data
in the container, which is the image’s working directly also.
To interact with the container, place (or symlink) the files on your host
into the ./docker/data
directory, which can then be seen and used in
the /data
directory in the container.
A quick demo of a typical scenario using kb:
A quick demo with kb aliases enabled:
A quick demo for non-text documents:
kb list
# or if aliases are used:
kbl
kb list zip
# or if aliases are used:
kbl zip
kb list --category cheatsheet
# or
kb list -c cheatsheet
# or if aliases are used:
kbl -c cheatsheet
kb list --tags "web;pentest"
# or if aliases are used:
kbl --tags "web;pentest"
kb list -v
# or if aliases are used:
kbl -v
kb add ~/Notes/cheatsheets/pytest
# or if aliases are used:
kba ~/Notes/cheatsheets/pytest
kb add ~/ssh_tunnels --title pentest_ssh --category "procedure" \
--tags "pentest;network" --author "gnc" --status "draft"
kb add ~/Notes/cheatsheets/general/* --category "cheatsheet"
kb add --title "ftp" --category "notes" --tags "protocol;network"
# a text editor ($EDITOR) will be launched for editing
kb add --title "my_network_scan" --category "scans" --body "$(nmap -T5 -p80 192.168.1.0/24)"
kb delete --id 2
# or if aliases are used:
kbd 2
kb delete --id 2 3 4
# or if aliases are used:
kbd 2 3 4
kb delete --title zap --category cheatsheet
kb view --id 3
# or
kb view -i 3
# or
kb view 3
# or if aliases are used:
kbv 3
kb view --title "gobuster"
# or
kb view -t "gobuster"
# or
kb view gobuster
kb view -t dirb -n
kb view -i 2 -e
# or if aliases are used:
kbv 2 -e
Editing artifacts involves opening a text editor. Hence, binary files cannot be edited by kb.
The editor can be set by the “EDITOR” environment variable.
kb edit --id 13
# or
kbe 13
# or if aliases are used:
kbe 13
kb edit --title "git" --category "cheatsheet"
# or
kb edit -t "git" -c "cheatsheet"
# or if git is unique as artifact
kb edit git
kb grep "[bg]zip"
# or if aliases are used:
kbg "[bg]zip"
kb grep -i "[BG]ZIP"
kb grep -v "[bg]zip"
kb grep -m "[bg]zip"
To export the entire knowledge base, do:
kb export
This will generate a .kb.tar.gz archive that can
be later be imported by kb.
If you want to export only data (so that it can be used in other software):
kb export --only-data
This will export a directory containing a subdirectory for each category and within these subdirectories we will have all the artifacts belonging to that specific category.
kb import archive.kb.tar.gz
NOTE: Importing a knowledge base erases all the previous
data. Basically it erases everything and imports the new knowledge base.
kb erase
kb supports custom templates for the artifacts. A template is basically a file using the “toml” format, structured in this way:
TITLES = [ "^#.*", "blue", ]
WARNINGS = [ "!.*" , "yellow",]
COMMENTS = [ ";;.*", "green", ]
Where the first element of each list is a regex and the second element is a color.
Note that by default an artifact is assigned with the ‘default’ template, and this template can be changed too (look at “Edit a template” subsection).
To list all available templates:
kb template list
To list all the templates containing the string “theory”:
kb template list "theory"
Create a new template called “lisp-cheatsheets”, note that an example template will be put as example in the editor.
kb template new lisp-cheatsheets
To delete the template called “lisp-cheatsheets” just do:
kb template delete lisp-cheatsheets
To edit the template called “listp-cheatsheets” just do:
kb template edit lisp-cheatsheets
We can also add a template from an already existing toml configuration file by just doing:
kb template add ~/path/to/myconfig.toml --title myconfig
We can change the template for an existing artifact by ID by using the update command:
kb update --id 2 --template "lisp-cheatsheets"
We can apply the template “lisp-cheatsheets” to all artifacts belonging to the category “lispcode” by doing:
kb template apply "lisp-cheatsheets" --category "lispcode"
We can apply the template “dark” to all artifacts having in their title the string “zip” (e.g., bzip, 7zip, zipper) by doing:
kb template apply "dark" --title "zip" --extended-match
# or
kb template apply "dark" --title "zip" -m
We can always have our queries to “contain” the string by using
the --extended-match
option when using kb template apply
.
We can apply the template “light” to all artifacts of the category “cheatsheet” who have as author “gnc” and as status “OK” by doing:
kb template apply "light" --category "cheatsheet" --author "gnc" --status "OK"
kb can be integrated with other tools.
We can integrate kb with rofi, a custom mode has been developed accessible in the “misc” directory within this repository.
We can launch rofi with this mode by doing:
rofi -show kb -modi kb:/path/to/rofi-kb-mode.sh
Synchronization with a remote git repository is experimental at the moment. Anyway we can initialize our knowledge base to a created empty github/gitlab (other git service) repository by doing:
kb sync init
We can then push our knowledge base to the remote git repository with:
kb sync push
We can pull (e.g., from another machine) our knowledge base from the remote git repository with:
kb sync pull
We can at any time view to what remote endpoint our knowledge is synchronizing to with:
kb sync info
If you want to upgrade kb to the most recent stable release do:
pip install -U kb-manager
If instead you want to update kb to the most recent release (that may be bugged), do:
git clone https://github.com/gnebbia/kb
cd kb
pip install --upgrade .
Q) How do I solve the AttributeError: module 'attr' has no attribute 's'
error?
A) Uninstall attr and use attrs:
pip uninstall attr
pip uninstall attrs
pip install attrs
pip install -U kb-manager
I am an independent developer working on kb in my free time, if you like kb and would like to say thank you, buy me a beer!
Copyright 2020 Giuseppe Nebbione.
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.