Chimp Documentation

1. What is Chimp?

Chimp is a native desktop application for Kali Linux — an all-in-one cybersecurity reference, training platform, and active testing workbench.

It is designed for security professionals and students who want a single pane of glass:

• Research a topic — browse 15 security domains and 129 AI-powered topics covering network security, application security, offensive techniques, defensive controls, cryptography, identity, cloud, malware, GRC, reverse engineering, mobile security, social engineering, hardware security, and dedicated Red Team and Blue Team domains.
• Understand threats — view CVE tables, MITRE ATT&CK mappings, real-world incidents, and threat actor intelligence.
• Read tools — explore a curated index of 75 open source tools with install commands and usage examples.
• Run the scan — inject commands directly into the integrated terminal with a single click.
• Practice hands-on — spin up DVWA, Metasploitable, or Juice Shop from the Lab Environment and practice against real vulnerable targets without touching any external system.
• Plan your engagement — create projects, generate AI playbooks, capture evidence per step, and export client-ready reports.

Chimp runs entirely on your local machine. AI responses are cached offline so content is never fetched twice.

2. Getting Started

2.1 Installation

Requirements

• Kali Linux (2023.x or later recommended)
• Node.js 20+
• Python 3.x with setuptools

Install from source

git clone https://github.com/your-org/chimp.git
cd chimp
npm install
pip3 install setuptools --break-system-packages   # Required for node-gyp on Python 3.12+
npm run rebuild                                    # Compile native modules against Electron
npm run dev                                        # Start in development mode

Install from package (.deb / AppImage)

# Debian package
sudo dpkg -i chimp_1.0.0_amd64.deb

# AppImage
chmod +x Chimp-1.0.0.AppImage
./Chimp-1.0.0.AppImage

2.2 First Launch

When Chimp opens for the first time you will be presented with the Registration screen. Complete this before accessing the app.

1. Enter a username and password (minimum 8 characters). Your password is never stored — only a secure hash is kept.
2. Enter your License Key (format: AEGIS-XXXX-XXXX-XXXX-XXXX).
3. Click Create Account.

On subsequent launches, Chimp will auto-login if your session is less than 30 days old. Otherwise, the login screen is shown.

2.3 Registration & License

License Key format: AEGIS-XXXX-XXXX-XXXX-XXXX

Chimp validates your license key on first use and periodically in the background.

To re-enter or update your license key: click the 👤 User icon at the bottom of the icon rail, then click Manage License.

2.4 Configuring Your AI Provider

Chimp uses the Claude API (Anthropic) by default to generate knowledge content and power the AI Security Assistant.

1. Click the ⚙ Settings icon in the icon rail (bottom).
2. Paste your API key into the API Key field (starts with sk-ant-).
3. Click Save.

The green dot in the header turns solid when a valid key is detected. Without an API key, all AI-powered features show a "Key required" message.

3. Navigation Overview

Chimp uses a 4-zone layout: a narrow icon rail, a context-driven secondary panel, the main content area, and a collapsible terminal panel.

• The active section is highlighted with a rose left border on its icon.
• Hover any icon for a tooltip label.
• The Secondary Panel can be collapsed by clicking its left edge.
• The Active Project Badge in the header shows your current project. Click it to switch projects.

4. Knowledge Base

4.1 Browsing Domains & Topics

The Knowledge Base organises security knowledge into 15 domains and 129 topics total.

• Click the 📚 Knowledge icon in the rail.
• The secondary panel shows the domain tree — click any domain header to expand / collapse its topics.
• Click any topic to load its detail view.
• Use the search bar at the top or press Ctrl+K to open global search.
• Keyboard navigation: ↑ / ↓ to move, Enter to select.

Red / Blue Team Mode Filter

Below the search bar there is a three-state toggle — 🔴 Red, ◎ All, 🔵 Blue.

Domain headers update their topic count to reflect the filtered set. Domains with no matching topics are hidden entirely. Your selection is saved and restored on next launch.

4.2 Topic Detail Tabs

Each topic opens a 6-tab detail view populated by AI (Claude). Content is cached after the first fetch.

Tab 1 — Overview

3–4 paragraph description, key concepts grid, "Why it matters" callout, and related topic links.

Tab 2 — Threat Intelligence

CVE table (CVSS colour-coded), MITRE ATT&CK technique chips, real-world incidents with dates, and threat actor intelligence (APT groups).

Tab 3 — Prevention & Hardening

Ordered checklist of security controls with priority badges (Critical / High / Medium), configuration snippets with [▶ Run] and [Copy] buttons, and NIST / ISO 27001 compliance mappings.

Tab 4 — Scanning & Detection

Tool cards for each relevant open-source scanner, install commands, and 3–5 example commands with [▶ Run in Terminal] and [Copy] buttons.

Tab 5 — Offensive Techniques

Same card format as Scanning, focused on offensive tools covering reconnaissance, exploitation, post-exploitation, and cleanup.

Tab 6 — Notes

Markdown text area that auto-saves as you type (keyed per topic). Toggle Preview to render sanitized markdown below the editor.

4.3 Cheat Sheet

Every topic has a Cheat Sheet button (📋) in the top-right of the detail view header, visible once AI content has loaded. Click it to open a full-panel overlay with a condensed summary of the topic.

The [▶] buttons in the cheat sheet inject the command into the active terminal as text — you must press Enter to execute, just like the detail tabs.

Export PDF renders the cheat sheet as a clean single-page PDF using Electron's print engine. A save dialog lets you choose the output path. Interactive controls are hidden in the PDF output.

Click ✕ Close or click the 📋 button again to dismiss the overlay.

4.4 Offline Caching

AI-generated content is cached locally — you only pay for an API call once per topic.

5. Integrated Terminal

Chimp embeds a full PTY terminal powered by xterm.js and node-pty.

5.1 Opening & Managing Tabs

• The terminal panel is on the right side. If collapsed, click the ◀ button on its left edge.
• Click + in the tab bar to open a new bash session.
• Double-click a tab name to rename it.
• Click × on a tab to close it.

5.2 Run in Terminal

Any [▶ Run] button in the content area injects that command into the active terminal tab.

By default, the command is NOT auto-executed. It is typed into the terminal so you can review it before pressing Enter. This protects you from accidentally running destructive commands.

To enable auto-execution (opt-in): open Settings → enable Auto-execute on Run.

5.3 Terminal Settings

6. Tools Index

The Tools Index provides a curated library of 75 open source security tools with metadata, install commands, and usage examples.

To open: click 📚 Knowledge in the rail, then switch the secondary panel to the Tools tab.

Each tool shows: name, license, and category badges; whether it is pre-installed on Kali; a description; official URL; install command; and 3–5 usage examples with [▶ Run] and [Copy] buttons.

Filter by category chips (Network, Web, Exploitation, Forensics, etc.) or type in the search bar to filter by name, description, or tag.

7. Global Search

Press Ctrl+K from anywhere in the app to open the global search overlay. Searches across topic names, tool names, and tool descriptions. Results are grouped: Topics and Tools. Press Escape to close.

8. Notes

Each topic has its own Notes tab (Tab 6) for freeform markdown notes. Notes auto-save as you type, are stored per topic (notes:domainId:topicId), and persist in ~/.config/Chimp/ across sessions.

9. My Topics

My Topics is a personal knowledge base where you can create, edit, and store your own security reference entries. Unlike the built-in Knowledge Base (AI-generated and read-only), My Topics entries are fully under your control — write them however you like and save them permanently.

Click the ✏️ icon in the icon rail to open My Topics.

9.1 Topic Types

When creating a new topic you choose a type that determines which tabs the editor provides:

All topic types include a Notes tab as the last tab.

9.2 Creating a Topic

1. Click the ✏️ My Topics icon in the icon rail.
2. Click [+ New Topic] in the secondary panel.
3. Enter a name (1–120 characters, required) and select a type.
4. Click [Create]. The editor opens immediately.

9.3 Editing a Topic

Click any tab in the editor to switch to it. Content auto-saves as you type — no Save button needed. A brief "Saved" indicator appears in the editor header after each save. Switching tabs or selecting a different topic flushes any pending auto-save immediately.

To rename: click [Rename] in the editor header, edit the title inline, and press Enter.

To delete: click [Delete] in the editor header and confirm. Deleted topics cannot be recovered.

9.4 Storage

My Topics are stored in ~/.config/Chimp/. They are not backed up or synced automatically — use your system's backup tools to preserve this directory.

10. Projects

Projects give you a persistent workspace to apply security knowledge and get AI advice for a specific system or engagement.

10.1 Creating a Project

1. Click the 📁 Projects icon in the rail.
2. Click [+ New Project] in the secondary panel.
3. Complete the 9-step wizard below.

Steps 1 and 3 (name) are required; all others are optional.

10.2 Project Dashboard

The dashboard shows the project name, industry badge, creation date, description, and five detail cards (Architecture, Platform, Components, Tech Stack, Compliance).

Dashboard actions:

• [Set as Active] — makes this the active project shown in the header.
• [Edit] — re-opens the wizard pre-filled with current values.
• [Delete] — removes the project (requires confirmation).
• [Change / Link Template] — opens a floating picker to link a different template.

10.3 Switching Active Projects

The active project is always visible as a badge in the header. Click it to open the Project Switcher dropdown and select a different project or create a new one.

10.4 Architecture Diagrams

Each project can store architecture diagrams as image attachments. Open the project dashboard, scroll to Architecture Diagrams, and click [+ Add Diagram]. Diagrams are stored in ~/.chimp/projects/assets/{projectId}/.

10.5 Playbooks

A Playbook is a structured security test plan auto-generated from your project's context — phases, steps, tools, commands, and expected severities.

How playbooks are generated

When you click [+ New], Chimp reads your project's industry, architecture, tech stack, compliance requirements, and linked template to identify applicable topics, collect testSteps, sort them into phases, and build the plan automatically. No manual configuration required.

Playbook phases

AI Enrichment

Click [✨ Enrich with AI] on any playbook to add AI-generated notes and CVSS score estimates to each step. Enriched playbooks show an enriched badge. Requires a valid API key.

10.6 Engagement Runs

An Engagement Run is an active execution of a playbook against a real target environment. Each run captures target variables, scope, tool output, and findings as you work through the steps.

Starting a run

1. Open a playbook (Projects → select project → Playbooks tab → select playbook).
2. Click [▶ New Run].
3. Fill in the Run Wizard: run name, environment (Staging / Production / Lab / Client VPN), scope notes, and target variables that replace {{placeholders}} in command templates.
4. Click [▶ Start Engagement Run].

Recording findings

For each step, fill in the Finding form:

Click [Save & Next →] to save and advance. Click [Skip] to mark the step as N/A. The run completes automatically when all steps are saved or skipped.

10.7 Evidence Trail

The Evidence Trail is a read-only summary of a completed or in-progress run showing all findings, run statistics, and the entry point for report generation.

Stats bar

From the Evidence Trail: click [📄 Generate Report] to open the Report Generator, or [▶ Resume Run] if the run is still in progress.

10.8 Reports & Export

The Report Generator produces a professional security engagement report. It opens as a modal from the Evidence Trail.

Report sections (toggle on/off)

Export formats

Click [✨ Generate with AI] in the Executive Summary section to generate a narrative summary from your run's findings. You can edit the text before exporting.

11. Templates

Templates are structured security frameworks for specific industries. They define threat context, relevant security domains, compliance scope, recommended tools, and certifications.

11.1 Built-in Templates

To browse: click 📋 Templates in the icon rail, then select the Built-in tab. Built-in templates cannot be deleted.

11.2 Creating Custom Templates

1. Click 📋 Templates in the icon rail.
2. Click [+ New Template] in the secondary panel.
3. Fill in: industry, threat context, security domains, architecture patterns, compliance scope, recommended tools, and certifications.
4. Click [Save Template].

To export: open a template and click [Export as JSON]. To use in a project: open a project dashboard and click [Change / Link Template], or select one in Step 2 of the project wizard.

12. AI Security Assistant

The AI Security Assistant is a project-aware chat interface providing AI-generated threat models, test plans, risk assessments, and security guidance.

12.1 Starting a Conversation

1. Click the 🤖 AI Assistant icon in the rail.
2. The secondary panel shows your conversation history for the active project.
3. Click [+ New Chat] to start a fresh conversation.
4. Type your message and press Enter to send. Use Shift+Enter for a newline.

12.2 Project Context

Every message automatically includes your active project's details as system context: industry, architecture, key components, platform, tech stack, compliance requirements, and project description. Responses are specific to your system — not generic advice.

12.3 Suggested Prompts

When a conversation is empty, Chimp shows 5 suggested prompts as clickable chips:

• "Generate a threat model for this project"
• "Create a security test execution plan"
• "List the top 10 risks based on our architecture"
• "Map our compliance requirements to security controls"
• "What attack surfaces does our tech stack expose?"

13. Settings

Open Settings by clicking the ⚙️ icon at the bottom of the icon rail. Settings are divided into three sections.

13.1 AI Provider

13.2 Terminal

13.3 Cache & Data

Tools Database — shows the current tools DB version and last check time. Click Check for Updates to manually fetch the remote GitHub feed. If a newer version is available it is applied immediately and the Tools Index re-renders.

Content Pack — manages the ~/.chimp/content/ directory (cached AI-generated topic JSON files).

• Export Pack — zips your content directory and saves it as chimp-content-vX.X.X.zip. Use this to back up or share your cached topics.
• Import Pack — opens a file picker to select a .zip and extracts it into ~/.chimp/content/, overwriting matching files. A confirmation dialog warns you before overwriting.
• Check Updates — checks the remote content manifest for a newer version; if available, an Install link appears to download and apply it automatically.

14. Keyboard Shortcuts

15. CLI Utility

Chimp ships with a command-line tool (chimp) installed alongside the desktop app. It exposes the same AI-powered security analysis — threat models, reports, and scan command generation — directly from the terminal, with no GUI required. Ideal for CI/CD pipelines or headless Kali environments.

Prerequisite: Node.js must be available (sudo apt install nodejs). The CLI reads your API key and settings from the desktop app's config — configure your AI provider in the desktop app first.

Commands

chimp init [--template <name>]

Interactively create a .chimp.json project config in the current directory. Walks through 9 questions: industry, system name, description, architecture, key components, platform, tech stack, and compliance requirements. Use --template to pre-fill answers from a built-in template.

chimp init
chimp init --template "Healthcare Cybersecurity"

chimp threat-model [--project <path>] [--json] [--output <file>]

Generate an AI threat model for the project defined in .chimp.json. Outputs structured markdown with executive summary, attack surface, threat actors, risks table, mitigations table, and compliance gaps. Use --json for machine-readable output.

chimp threat-model
chimp threat-model --output threat-model.md
chimp threat-model --json --output threat-model.json

chimp scan <tool> [--execute] [--json] [--output <file>]

Look up a tool by id or name and generate the recommended scan command filled with your project's context. By default prints the command only — nothing executes. Add --execute to run the command and save its output as a run record in ~/.chimp/runs/.

chimp scan nmap               # prints: nmap -sV -sC <target>
chimp scan nmap --execute     # runs it, saves output
chimp scan burpsuite --json   # dry-run output as JSON

chimp report [--project <path>] [--json] [--output <file>]

Generate a full security assessment report. Combines project metadata with any scan run records from ~/.chimp/runs/ and calls AI for an executive summary, findings table, risk register, compliance assessment, and recommendations.

chimp report --output report.md
chimp report --json --output report.json

chimp template list [--json]

List all built-in templates in a formatted table (or JSON with --json).

chimp template list
chimp template list --json

chimp template apply <name> [--output <path>]

Generate a pre-filled .chimp.json from a built-in template. A good starting point before running chimp init to complete the remaining details.

chimp template apply "Automotive Security"
chimp template apply "SaaS / Cloud Security" --output /tmp/project.json

Output Formats

All AI commands (threat-model, report) support three output modes:

Errors always go to stderr — stdout is always clean, making pipes safe:

chimp threat-model | tee threat-model.md | wc -l

CI/CD Usage

The CLI is designed to run in automated pipelines on Kali or any Linux CI runner with Node.js. Store your .chimp.json in the repository root. The API key is read from the desktop app's config — pre-populate ~/.config/chimp/chimp-data.json from a CI secret, or copy the config from a configured machine.

# Example: generate threat model and report in CI
chimp threat-model --output threat-model.md
chimp report --output security-report.md

16. Lab Environment

The Lab Environment lets you spin up intentionally vulnerable Docker targets from inside Chimp and practice against them with live tool commands — without touching any external system.

16.1 Prerequisites

Docker must be installed. If Chimp detects that Docker is missing, the Lab content area shows an install guide.

sudo apt install docker.io docker-compose-plugin
docker compose version   # verify install
sudo usermod -aG docker $USER   # run without sudo (then log out and back in)

16.2 Launching a Lab

1. Click the 🧪 icon in the icon rail.
2. The secondary panel shows three lab cards: DVWA, Metasploitable 2, and OWASP Juice Shop.
3. Click the lab name or ▶ Launch. If a different lab is running, a confirmation dialog asks whether to stop it first.
4. Once the status badge turns ● Running, click 🌐 Open in Browser to open the lab in your default browser.

The running panel shows: container name, Docker bridge IP, and mapped ports — everything you need to target it from terminal tools.

16.3 DVWA Walkthrough

DVWA (Damn Vulnerable Web Application) is the recommended starting point. It covers 16 web vulnerability modules with adjustable difficulty levels.

First-time setup (database initialisation)

1. Open http://localhost:4280 in your browser.
2. Login with admin / password.
3. Scroll to the bottom of the setup page and click Create / Reset Database.
4. DVWA restarts. Login again with admin / password — you are now in the dashboard.

Security levels

DVWA modules and linked Chimp topics

16.4 Target Auto-Injection

When a lab is running, Chimp automatically substitutes the lab's Docker bridge IP into any [▶ Run] command that contains the <target> placeholder.

For example, a command template like sqlmap -u "http://<target>:4280/..." becomes sqlmap -u "http://172.18.0.2:4280/..." when DVWA is running. The live IP is shown in the 🧪 pill in the app header — visible from any section so you always know a lab is active.

16.5 Stopping Labs

• From the header pill: click × on the 🧪 IP pill in the header.
• From the Lab panel: click ⏹ Stop Lab, or launch a different lab (you will be asked to confirm stopping the current one).
• On app quit: Chimp automatically stops all running containers before exiting. A brief delay on quit is normal if a lab is running.

17. Security & Privacy

Chimp is built with security as a first-class concern. It runs on Kali Linux, often as root, and embeds a live terminal — the app must not introduce vulnerabilities into the machine it is protecting.

What is stored on your machine

Network connections

• Anthropic API (api.anthropic.com) — only when AI content is requested and not cached.
• OpenAI API (api.openai.com) — only when fetching the live model list for an OpenAI-configured provider.
• License server (api.chimp.io) — on first use and periodically for license validation.
• GitHub (raw) (raw.githubusercontent.com) — on app start and on "Check for Updates" to fetch the tools feed and content manifest.
• No telemetry, analytics, or crash reporting is sent.

What is NOT stored

• Passwords — only a bcrypt hash (10 rounds) is stored, never the plaintext.
• API key in the renderer process — all AI calls happen in the main process only.
• API key in logs or error messages.

18. Troubleshooting

App won't start / blank screen

1. Check that npm run rebuild was run after npm install.
2. Verify node-pty compiled: ls node_modules/node-pty/build/.
3. Run npm run dev in terminal — errors are printed to stdout.

"API key is not set" — but I entered my key

1. Open Settings and re-enter the key — ensure it starts with sk-ant-.
2. Check the green dot in the header changes after saving.
3. Click Clear Cache in Settings and retry.

Terminal is blank / PTY not connecting

1. Ensure /bin/bash exists: which bash.
2. Try setting the shell to /bin/zsh in Settings.
3. Run npm run rebuild — node-pty must be compiled for the current Electron version.

Force-clear the cache

rm -rf ~/.config/Chimp/

Registration screen appears on every launch

Your session may have expired (sessions are valid for 30 days). Log in with your username and password to restore it.

19. FAQ

Can I use Chimp without an API key?

The Knowledge tree and Tools Index are fully browsable without an API key. AI-generated topic content and the AI Security Assistant require a valid API key.

Which AI providers are supported?

Chimp's AI client supports Anthropic Claude (default), OpenAI, Google Gemini, DeepSeek, and local Ollama models. Anthropic Claude is the recommended provider for best results.

Are my notes and conversations backed up?

Not automatically. Notes, My Topics, and project data are stored in ~/.chimp/ and ~/.config/Chimp/. Back these directories up manually. The Export feature in the AI Assistant exports individual conversations as markdown files. Use Settings → Cache & Data → Export Pack to back up your cached topic content as a portable zip.

How do I transfer my cached content to another machine?

Go to Settings → Cache & Data, click Export Pack to save a .zip of your ~/.chimp/content/ directory. On the target machine click Import Pack and select the file.

Will the tools list update automatically?

Yes — Chimp checks the remote tools feed on startup. If a newer version is available it updates the Tools Index without requiring a reinstall. You can also trigger a manual check in Settings → Cache & Data → Tools Database.

Can I use Chimp on a non-Kali Linux distribution?

Yes — the app is an Electron application and should work on any modern Linux distribution with Node.js 20 and Python 3. Kali is the primary supported platform.

Is Chimp available for macOS or Windows?

Not in the current version. Kali Linux is the only supported platform. Cross-platform builds are on the roadmap.

What does "read-only mode" mean?

If your license key is missing or invalid, AI features and project creation are disabled. You can still browse the Knowledge tree and Tools Index. Your existing notes remain accessible.

Can I run Chimp as a non-root user?

Yes. Chimp does not require root. However, many Kali security tools (nmap, etc.) require root or sudo. Running the app as root gives you a terminal that can execute those tools directly.

How do I report a bug?

Open an issue at github.com/your-org/chimp/issues with your Kali version, Node.js version, and steps to reproduce the problem.