kb. A minimalist knowledge base manager

You can get support for kb here

Author: gnc nebbionegiuseppe@gmail.com

Copyright: © 2020, gnc

Date: 2021-03-26

Version: 0.1.6

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
• DONATIONS
• COPYRIGHT

Purpose

kb is a text-oriented minimalist command line knowledge base manager. kbcan be considered a quick note collection and access tool oriented towardsoftware developers, penetration testers, hackers, students or whoeverhas to collect and organize notes in a clean way. Although kb is mainlytargeted 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 wayto quickly access my notes, procedures, cheatsheets and lists (e.g.,payloads) but at the same time, keeping them organized. This isparticularly useful for any kind of student. I use it in the contextof penetration testing to organize pentesting procedures, cheatsheets,payloads, guides and notes.

I found myself too frequently spending time trying to search for thatparticular payload list quickly, or spending too much time trying to finda specific guide/cheatsheet for a needed tool. kb tries to solve thisproblem 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 intoan organized knowledge base;
• filter the knowledge base on different metadata: title, category,tags and others;
• visualize items within the knowledge base with (or without) syntaxhighlighting;
• 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 havesome 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 issuethe following commands, after having inserted the path to your desiredtext 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 issuethe following commands, after having inserted the path to your desiredtext 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 pastethe 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 usekb in the running container as you would if you installed it on thehost 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 hostinto the ./docker/data directory, which can then be seen and used inthe /data directory in the container.

Usage

A quick demo of a typical scenario using kb:

A quick demo with kb aliases enabled:

A quick demo for non-text documents:

List artifacts

List all artifacts contained in the kb knowledge base

kb list

# or if aliases are used:
kbl

List all artifacts containing the string "zip"

kb list zip

# or if aliases are used:
kbl zip

List all artifacts belonging to the category "cheatsheet"

kb list --category cheatsheet
# or
kb list -c cheatsheet

# or if aliases are used:
kbl -c cheatsheet

List all the artifacts having the tags "web" or "pentest"

kb list --tags "web;pentest"

# or if aliases are used:
kbl --tags "web;pentest"

List using "verbose mode"

kb list -v

# or if aliases are used:
kbl -v

Add artifacts

Add a file to the collection of artifacts

kb add ~/Notes/cheatsheets/pytest

# or if aliases are used:
kba ~/Notes/cheatsheets/pytest

Add a file to the artifacts

kb add ~/ssh_tunnels --title pentest_ssh --category "procedure" \
    --tags "pentest;network" --author "gnc" --status "draft"

Add all files contained in a directory to kb

kb add ~/Notes/cheatsheets/general/* --category "cheatsheet"

Create a new artifact from scratch

kb add --title "ftp" --category "notes" --tags "protocol;network"
# a text editor ($EDITOR) will be launched for editing

Create a new artifact from the output of another program

kb add --title "my_network_scan" --category "scans" --body "$(nmap -T5 -p80 192.168.1.0/24)"

Delete artifacts

Delete an artifact by ID

kb delete --id 2

# or if aliases are used:
kbd 2

Delete multiple artifacts by ID

kb delete --id 2 3 4

# or if aliases are used:
kbd 2 3 4

Delete an artifact by name

kb delete --title zap --category cheatsheet

View artifacts

View an artifact by id

kb view --id 3
# or
kb view -i 3
# or 
kb view 3

# or if aliases are used:
kbv 3

View an artifact by name

kb view --title "gobuster"
# or
kb view -t "gobuster"
# or
kb view gobuster

View an artifact without colors

kb view -t dirb -n

View an artifact within a text-editor

kb view -i 2 -e

# or if aliases are used:
kbv 2 -e

Edit artifacts

Editing artifacts involves opening a text editor.Hence, binary files cannot be edited by kb.

The editor can be set by the "EDITOR" environmentvariable.

Edit an artifact by id

kb edit --id 13
# or
kbe 13
# or if aliases are used:
kbe 13

Edit an artifact by name

kb edit --title "git" --category "cheatsheet"
# or
kb edit -t "git" -c "cheatsheet"
# or if git is unique as artifact
kb edit git

Grep through artifacts

Grep through the knowledge base

kb grep "[bg]zip"

# or if aliases are used:
kbg "[bg]zip"

Grep (case-insensitive) through the knowledge base

kb grep -i "[BG]ZIP"

Grep in "verbose mode" through the knowledge base

kb grep -v "[bg]zip"

Grep through the knowledge base and show matching lines

kb grep -m "[bg]zip"

Import/Export/Erase a knowledge base

Export the current knowledge base

To export the entire knowledge base, do:

kb export

This will generate a .kb.tar.gz archive that canbe 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 categoryand within these subdirectories we will have all the artifacts belongingto that specific category.

Import a knowledge base

kb import archive.kb.tar.gz

NOTE: Importing a knowledge base erases all the previousdata. Basically it erases everything and imports the new knowledge base.

Erase the entire knowledge base

kb erase

Manage Templates

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

List available templates

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

Create a new template called "lisp-cheatsheets", note thatan example template will be put as example in the editor.

kb template new lisp-cheatsheets

Delete a template

To delete the template called "lisp-cheatsheets" just do:

kb template delete lisp-cheatsheets

Edit a template

To edit the template called "listp-cheatsheets" just do:

kb template edit lisp-cheatsheets

Add a template

We can also add a template from an already existing toml configuration fileby just doing:

kb template add ~/path/to/myconfig.toml --title myconfig

Change template for an artifact

We can change the template for an existing artifact by ID by using theupdate command:

kb update --id 2 --template "lisp-cheatsheets"

Apply a template to all artifacts of a category

We can apply the template "lisp-cheatsheets" to all artifactsbelonging to the category "lispcode" by doing:

kb template apply "lisp-cheatsheets" --category "lispcode"

Apply a template to all artifacts having zip in their title

We can apply the template "dark" to all artifacts having in their titlethe 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 usingthe --extended-match option when using kb template apply.

Apply a template to all artifacts having specific properties

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"

Integrating kb with other tools

kb can be integrated with other tools.

kb and rofi

We can integrate kb with rofi, a custom mode has been developedaccessible 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

Experimental

Synchronize kb with a remote git repository

Synchronization with a remote git repository is experimental at the moment.Anyway we can initialize our knowledge base to a created emptygithub/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 theremote git repository with:

kb sync pull

We can at any time view to what remote endpoint our knowledge is synchronizingto with:

kb sync info

UPGRADE

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 .

DONATIONS

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

Copyright 2020 Giuseppe Nebbione.

This program is free software: you can redistribute it and/or modifyit under the terms of the GNU General Public License as published bythe 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 ofMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See theGNU General Public License for more details.

You should have received a copy of the GNU General Public Licensealong with this program. If not, see http://www.gnu.org/licenses/.