A Discord bot for searching the Common Vulnerabilities and Exposures (CVE) list and providing Known Exploitable Vulnerabilities (KEV) updates.

---

Table of Contents

• About
  • Built With
  • Usage
  • Screenshots
• Getting Started
  • Prerequisites
  • Configuration
  • Running with Docker (Recommended)
  • Running Locally with Poetry
• Roadmap
• Support
• Contributing
• Authors & contributors
• Security
• License
• Acknowledgements

---

About

kevvy is a Discord bot with the following main functions:

1. Automatic CVE Detection: It automatically monitors chat messages for CVE (Common Vulnerabilities and Exposures) identifiers (e.g., CVE-2023-12345). When a CVE is detected, the bot fetches detailed information using VulnCheck as the primary source if a VULNCHECK_API_TOKEN is provided, falling back to the NIST National Vulnerability Database (NVD) API v2.0 otherwise.
2. Direct CVE Lookup: Users can explicitly request details for a specific CVE using the /cve lookup command.
3. CISA KEV Monitoring: Optionally monitors the CISA Known Exploited Vulnerabilities (KEV) catalog and sends alerts for new entries to configured channels.

Key features:

• Automatic detection of CVE IDs in messages.
• Direct lookup of specific CVEs via /cve lookup.
• Fetches details using VulnCheck first (if VULNCHECK_API_TOKEN is configured), then NVD.
• Displays CVSS score (v3.1/v3.0/v2.0), vector string, description, publication dates, CWEs, and reference links.
• Consolidates responses for messages containing multiple CVEs (max 5 embeds per message by default, with delays between sends) to prevent spam.
• Optionally checks the CISA KEV catalog periodically and posts alerts for new entries to a designated channel (configurable per server).

Built With

• 
• 
• 
• 
• 
• 
• 

Usage

1. Invite the Bot: Invite the configured bot to your Discord server.

2. Automatic Detection: Simply type or paste a message containing one or more CVE IDs (e.g., Check out CVE-2024-1234 and CVE-2024-5678). The bot will automatically detect them and post embed(s) with the details. The verbosity of the details depends on server and channel settings (see /verbose commands).

   • If multiple unique CVEs are in one message, the bot will post details for up to 5 of them (by default) and indicate if more were found.

3. Direct CVE Lookup: Use the slash command /cve lookup cve_id:<CVE-ID> (e.g., /cve lookup cve_id:CVE-2024-0001) to get details for a specific vulnerability.

4. CISA KEV Alerts (Optional Setup):

   • /kev feed enable channel:<#your-alert-channel>: A server administrator with 'Manage Server' permissions can run this command to enable KEV monitoring and designate a specific channel for alerts.
   • /kev feed disable: Disables KEV alerts for the server.
   • /kev feed status: Checks the status of KEV monitoring.
   • /kev latest [count] [days] ...: Shows the latest KEV entries with optional filters.

5. CVE Monitoring Channel Configuration:

   • /cve channel add channel:<#channel>: Enables automatic CVE scanning for messages in the specified channel. Ensures global monitoring is also enabled for the server.
   • /cve channel remove channel:<#channel>: Removes automatic CVE monitoring configuration for the specified channel.
   • /cve channel list: Shows the global CVE monitoring status (enabled/disabled) and lists channels configured for scanning.
   • /cve channel enable_global: Enables automatic CVE message scanning globally for the server (channels still need to be added via /cve channel add to be monitored).
   • /cve channel disable_global: Disables automatic CVE message scanning globally for the server. No messages will be scanned in any channel.

6. Alert Verbosity Configuration:

   • /verbose enable_global: Sets the default alert style to verbose for the whole server.
   • /verbose disable_global: Sets the default alert style to standard (non-verbose) for the whole server.
   • /verbose set channel:<#channel> verbosity:<True|False>: Overrides the verbosity setting for a specific channel.
   • /verbose unset channel:<#channel>: Removes the override for a specific channel (it uses the global setting).
   • /verbose setall verbosity:<True|False>: Sets an override for all channels.
   • /verbose status [channel]: Shows the current global and channel-specific verbosity settings.

7. CVE Threshold Configuration:

   • /cve threshold set <level>: Sets the minimum CVSS severity (critical, high, medium, low, all) required for a CVE mentioned in a message to trigger an automatic alert (global server setting).
   • /cve threshold view: Shows the current global severity threshold.
   • /cve threshold reset: Resets the global severity threshold to all.

8. Help Command:

   • /kevvy help [command_name]: Shows a general overview of all command groups, or detailed help for a specific command or command group (e.g., /kevvy help cve or /kevvy help cve lookup).

9. Admin Commands (Bot Owner Only):

   • /kevvy admin status: Shows the operational status of the bot (uptime, server count, etc.)
   • /kevvy admin stats: Shows detailed statistics about the bot's operations (command usage, CVE lookups, etc.)
   • /kevvy admin reload [extension]: Reloads bot extensions/cogs (useful for applying code changes without restarting)
   • /kevvy admin version: Shows detailed version information for the bot
   • /kevvy admin servers: Lists all servers the bot is in
   • /kevvy admin debug <code>: Evaluates Python code for debugging
   • /kevvy admin announce <message>: Sends an announcement message to all servers the bot is in

     Note: These commands are restricted to the bot owner only (configured via BOT_OWNER_ID).

Screenshots

Here's the bot in action:

Automatic CVE Detection and Information:

CISA KEV Alert Notification:

Web Dashboard Status:

Getting Started

Prerequisites

• Docker and Docker Compose (Recommended for running)
• OR Python 3.10+ and Poetry (For local development/running)
• A Discord Bot Token. You can create a bot and get a token from the Discord Developer Portal.

Configuration

The bot is configured using environment variables. Create a .env file in the project root by copying the example:

cp .env.example .env

Then, edit the .env file:

• DISCORD_TOKEN (Required): Your Discord bot token.
• NVD_API_KEY (Optional): Your NVD API key. Request one here for significantly higher request rate limits. Used as a fallback data source if VulnCheck is not configured or fails.
• VULNCHECK_API_TOKEN (Optional): Your VulnCheck API key. If provided, Kevvy will use VulnCheck as the primary source for CVE details, offering richer information. Get one from VulnCheck.

• DISCORD_COMMAND_PREFIX (Optional): The prefix for traditional commands (if any are added later). Defaults to !. The primary interaction is automatic detection and slash commands.
• LOGGING_CHANNEL_ID (Optional): The ID of the Discord channel to which log messages should be sent.
• DISABLE_DISCORD_LOGGING (Optional): Set to true to disable sending logs to the Discord channel specified by LOGGING_CHANNEL_ID. Defaults to false.

Running with Docker (Recommended)

1. Ensure Docker and Docker Compose are installed.
2. Make sure you have configured your .env file (especially DISCORD_TOKEN).
3. Start the bot container in detached mode:

   docker-compose up -d --build

   (This will automatically pull the ghcr.io/mauvehed/kevvy:latest image if you don't have it locally).
4. View Logs:

   docker-compose logs -f kevvy-bot

5. Stop Container:

   docker-compose down

Running Locally with Poetry

1. Ensure Python 3.10+ and Poetry are installed.
2. Clone the repository: git clone https://github.com/mauvehed/kevvy.git && cd kevvy
3. Install bot dependencies: poetry install
4. Configure your .env file.
5. Run the bot: poetry run python main.py

Roadmap

See the open issues for a list of proposed features (and known issues).

• Top Feature Requests (Add your votes using the 👍 reaction)
• Top Bugs (Add your votes using the 👍 reaction)
• Newest Bugs (Squash Em!)

Support

Reach out to the maintainer at one of the following places:

• Contact options listed on this GitHub profile
• @mauvehed just about anywhere else online

Contributing

First off, thanks for taking the time to contribute! Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make will benefit everybody else and are greatly appreciated.

Please read our contribution guidelines, and thank you for being involved!

The project includes automated testing using pytest and CI checks via GitHub Actions to help maintain code quality.

Authors & contributors

The original setup of this repository is by mauvehed.

For a full list of all authors and contributors, see the contributors page.

Security

• kevvy follows good practices of security, but 100% security cannot be assured.
• kevvy is provided "as is" without any warranty. Use at your own risk.

Please report security vulnerabilities privately via GitHub's Private Vulnerability Reporting feature (go to the 'Security' tab -> 'Report a vulnerability'). For more information on our security practices, see our security policy.

License

This project is licensed under the MIT license.

See LICENSE for more information.

Acknowledgements

• Data sourced primarily from VulnCheck (if configured) and NVD.
• Known Exploited Vulnerabilities feed monitored via CISA.
• Thanks to all contributors and users who have helped make this project better!