shenjunjiekoda / knight

kight is a static analysis tool for c/c++ programs.

Knight

Knight is a static analysis tool for C/C++ programs written in C++20.

Install

knight dependencies

• cmake
• llvm/clang(>=18 is best)
• GMP (>= 6 is best)

You can install llvm by your package manager

apt install llvm libgmp-dev libedit-dev # for Ubuntu
brew install llvm gmp # for Homebrew
yum install llvm gmp-devel libedit-devel # for CentOS
sudo pacman -S llvm gmp # for Arch Linux

or build from source.

Install knight by following steps

cd knight
chmod +x scripts/install
# scripts/install --help
scripts/install

or run step by step:

cd knight
cmake -DLLVM_BUILD_DIR=/path/to/llvm/build -B path-to-build -S .
cmake --build path-to-build -j$(nproc)
path-to-build/bin/knight --help # for usages

Note: Knight only support C++20, so you need to use a cpp compiler support C++20.

Test

Use scripts/unittest to run all unit tests.

Troubleshooting

See TROUBLESHOOTING.md for more details.

Contributing

Contributions are welcome, See CONTRIBUTING.md for more details

Licence

Knight is MIT-licensed, see LICENSE for more details

knight's Issues

Build Configuration Enhancement

While exploring the project's configuration setup, I noticed a potential area for improvement in the CMakeLists.txt and related build scripts. Specifically, the handling of LLVM and Clang dependencies could be enhanced to ensure a more flexible and robust build process. This is crucial for accommodating various development environments and LLVM versions.

Suggested Improvements ----

1. LLVM and Clang Version Compatibility: The project currently seems to target a specific version of LLVM/Clang. It would be beneficial to include checks or compatibility layers to support a range of versions, enhancing the project's usability across different environments.
2. Finding LLVM/Clang Packages: The script could leverage find_package more effectively to locate LLVM and Clang installations. This approach allows for more flexibility, especially when LLVM/Clang is installed in non-standard locations.
3. Documentation on Dependencies: While the README.md provides some information on dependencies, a more detailed guide on installing and configuring LLVM/Clang for this project would be helpful. This guide could cover different operating systems and common pitfalls.
4. Automated Dependency Checks: Incorporating automated checks for required dependencies within the CMake configuration can prevent common build errors. For example, checking if the correct version of LLVM/Clang is installed before proceeding with the build process.
5. Enhanced Support for LLVM's llvm-config: Utilizing llvm-config to set up compiler and linker flags can simplify the build process. This tool provides a reliable method to configure projects based on the installed LLVM/Clang version.
6. Build Directory Configuration: The script sets a custom build directory within the source tree. Adopting a more conventional out-of-source build directory approach can help avoid potential issues with source tree pollution and make cleanup easier.

Implementing these suggestions could significantly improve the project's build system, making it more accessible and easier to use across various development setups. I look forward to seeing these enhancements in future updates.

Thank you for your hard work on this project! Great work!

Use machine number as numerical base

Use machine integer with specific bitwidth is more accurate in numerical analysis

FR: Support for Custom Analysis Plugins

Hi @shenjunjiekoda

I've been exploring the knight project and am impressed with its capabilities and the analyses it performs on C/C++ codebases. However, I noticed that while the project supports a wide range of analyses and checks, there might be specific needs or custom analyses that users might want to perform which are not currently supported out-of-the-box.

Feature Request

I propose the addition of a feature that allows users to easily plug in their custom analyses into the knight framework. This would not only enhance the flexibility of the tool but also enable a broader community contribution by allowing users to share their custom analyses with others.

Suggested Approach

• Define a clear interface or protocol that custom analyses need to adhere to. This might include specific methods for analysis initialization, execution, and results reporting.
• Provide detailed documentation and examples on how to create custom analyses adhering to the proposed interface.
• Implement a mechanism within the knight tool to dynamically load and execute these custom analyses. This could be through shared libraries, scripts, or any other suitable form of extensibility.

Benefits

• Flexibility: Users can tailor the tool to their specific needs, enhancing its utility.
• Community Engagement: Encourages the community to contribute by developing and sharing their analyses.
• Rapid Prototyping: Users can quickly test new analyses without waiting for them to be officially incorporated into the tool.

Conclusion

The addition of support for custom analysis plugins could significantly enhance the knight tool's versatility and its adoption. I believe this feature aligns well with the project's goals of providing a comprehensive analysis tool for C/C++ codebases.

Thank you for considering this feature request. I am looking forward to any feedback or thoughts on this proposal.

Improve error handling and diagnosis

Severity: Minor

Description:
The current error handling and diagnosis in the knight project could be improved. There are several areas where the error handling can be enhanced:

1. Inconsistent error reporting: The project uses a mix of llvm::errs(), llvm::WithColor::error(), and custom error reporting mechanisms. This can lead to inconsistent error messages and formatting.

2. Lack of detailed diagnostics: When errors occur, the project often does not provide enough context or details to help users understand and resolve the issues. For example, when a YAML file fails to load, the error message could be more informative.

3. Limited user feedback: The current error handling does not provide much feedback to the user on the overall status of the analysis or the actions being taken. Users may not be aware of the progress or issues during the analysis.

4. Unclear exit codes: The project uses custom exit codes to indicate different error conditions, but the meaning of these codes is not well documented. It would be helpful to have a clear mapping between exit codes and error conditions.

Recommendations:

1. Standardize error reporting: Adopt a consistent approach to error reporting across the project, potentially using a centralized error handling mechanism or utilities. This can improve the clarity and consistency of error messages.

2. Provide more detailed diagnostics: When errors occur, include more context and information to help users understand the issue and identify the root cause. This can include reporting the specific file, location, and other relevant details.

3. Improve user feedback: Consider adding progress reporting, status updates, and other feedback mechanisms to keep users informed about the analysis process and any issues encountered.

4. Document exit codes: Clearly document the meaning and purpose of each exit code used by the project, making it easier for users to interpret the results.

Benefits:
Implementing these improvements will enhance the overall user experience and make it easier for users to diagnose and resolve issues when using the knight project. This can lead to better adoption, fewer support requests, and a more robust and reliable static analysis tool.

Installation Script Missing Error Handling

Description

The installation script (scripts/install) lacks error handling for various potential issues that could arise during the installation process. This can lead to unclear failure points and make troubleshooting difficult for users.

Steps to Reproduce

1. Clone the repository.
2. Run the installation script with incorrect paths or missing dependencies.
3. Observe that the script does not handle errors gracefully, leading to potential confusion.

Expected Behavior

The installation script should:

• Check if the provided paths (e.g., --project-build-dir, --llvm-build-dir) exist and are valid directories.
• Verify that required dependencies (e.g., CMake, LLVM) are installed before proceeding.
• Provide clear error messages if any of the required steps fail.

Actual Behavior

The script proceeds without checking for these conditions, which can result in cryptic error messages or incomplete installations.

Proposed Solution

Add error handling to the installation script to check for the following:

• Validity of provided directory paths.
• Existence of required dependencies (e.g., CMake, LLVM).
• Successful execution of each step in the installation process.

Below is a suggested modification to the script:

#!/usr/bin/python3

# ===- install --------------------------------------------------------===#
#
# Copyright (c) 2024 Junjie Shen
#
# see https://github.com/shenjunjiekoda/knight/blob/main/LICENSE for
# license information.
#
# ===------------------------------------------------------------------===#
#
#  This script setup and build knight.
#
# ===------------------------------------------------------------------===#

import argparse
import subprocess
import sys
import os
from pathlib import Path
import shutil

def check_directory(path, name):
    if not path.exists() or not path.is_dir():
        print(f"Error: The {name} directory '{path}' does not exist or is not a directory.", file=sys.stderr)
        sys.exit(1)

def check_dependency(command, name):
    if shutil.which(command) is None:
        print(f"Error: {name} is not installed or not found in PATH.", file=sys.stderr)
        sys.exit(1)

def main():
    parser = argparse.ArgumentParser(
        description="Install and build the knight project."
    )
    parser.add_argument(
        "--project-build-dir", type=Path, help="Path to the project build directory."
    )
    parser.add_argument(
        "--llvm-build-dir", type=Path, help="Path to the LLVM build directory."
    )
    parser.add_argument(
        "--cleanup",
        action="store_true",
        help="Clean up the project build directory before building.",
    )
    parser.add_argument("--c_compiler", type=str, help="Path to the C compiler.")
    parser.add_argument("--cpp_compiler", type=str, help="Path to the C++ compiler.")

    args = parser.parse_args()

    # Determine the absolute path of the project root directory (assumes this script is in <project_root>/scripts)
    abs_path = Path(__file__).resolve().parent.parent

    # Determine the project build directory
    if args.project_build_dir is None:
        args.project_build_dir = abs_path / "build"

    # Check directories
    check_directory(args.project_build_dir, "project build")
    check_directory(args.llvm_build_dir, "LLVM build")

    # Check dependencies
    check_dependency("cmake", "CMake")
    check_dependency("clang", "LLVM/Clang")

    # Rest of the script...

if __name__ == "__main__":
    main()

Additional Information

Adding these checks will improve the robustness of the installation process and provide users with clearer guidance on how to resolve issues that may arise.

Thank you for your attention to this matter!

Enhance Documentation for First-Time Contributors

As a potential contributor, I found the project documentation lacking in some areas that would help newcomers get started more easily.

Suggested Improvements:

1. Add a "Quick Start" guide in the README
2. Provide more detailed installation instructions for different operating systems
3. Include a simple example of how to use Knight on a C/C++ program
4. Create a "Contributing" section with steps for setting up a development environment

These additions would significantly lower the barrier to entry for new contributors and users of Knight.

Let me know if you'd like me to elaborate on any of these points or assist with implementing them.

Installation Instructions Clarification

Description

The installation instructions for the Knight project, as detailed in the README.md file, could benefit from additional clarity and detail to assist users in setting up the project efficiently. Specifically, the instructions for setting up LLVM dependencies and building the project could be expanded to cover common issues and provide more guidance for users unfamiliar with the process.

Suggested Enhancements

1. Detailed Dependency Versions: The instructions mention LLVM/Clang version 18 as the best option, but it would be helpful to specify if earlier versions are supported and, if so, which ones. Including information about compatibility can prevent users from encountering unexpected issues during installation.

2. Expanded LLVM Installation Instructions: While the instructions provide commands for installing LLVM via package managers, they could include steps or links for verifying a successful installation. This might involve checking the LLVM version or ensuring that LLVM's binaries are correctly added to the user's PATH.

3. Clarification on Building from Source: The option to build LLVM from source is mentioned, but additional details or a link to a step-by-step guide could be beneficial. Building LLVM from source can be a complex process, especially for users who are not familiar with it.

4. Troubleshooting Common Issues: A brief section on troubleshooting common issues during the installation process could be very helpful. This might include errors related to missing dependencies, issues with CMake configurations, or problems encountered when running the scripts/install script.

5. Example Configuration for Building: The instructions mention running CMake with specific flags for the LLVM build directory but do not provide a complete example command. An explicit example that includes typical paths or configurations might reduce confusion and help users understand how to adapt the command to their setups.

6. Verification Step: After installation, including a step to verify that Knight has been installed correctly could improve user confidence in the setup process. This could be as simple as running a version check or a command that displays a help menu.

Conclusion

Enhancing the installation instructions with these details could significantly improve the user experience, especially for those less familiar with the tools and processes involved in setting up C++ projects. Providing clearer guidance and troubleshooting tips would make the project more accessible to a wider audience.

crash on mac os

crash on mac , using command:

$ knight -checkers="*" --dump-cfg test/testcase/b.cpp

stack frames dump backtrace:

PLEASE submit a bug report to https://github.com/Homebrew/homebrew-core/issues and include the crash backtrace.
Stack dump:
0.      Program arguments: knight -checkers=* --dump-cfg test/testcase/b.cpp
 #0 0x000000011b359d60 llvm::sys::PrintStackTrace(llvm::raw_ostream&, int) (/opt/homebrew/Cellar/llvm/18.1.8/lib/libLLVM.dylib+0x4695d60)
 #1 0x000000011b35a134 SignalHandler(int) (/opt/homebrew/Cellar/llvm/18.1.8/lib/libLLVM.dylib+0x4696134)
 #2 0x0000000188f86584 (/usr/lib/system/libsystem_platform.dylib+0x18047a584)
 #3 0x00000001094d9c6c llvm::FoldingSetImpl<llvm::FoldingSet<knight::dfa::ProgramState>, knight::dfa::ProgramState>::RemoveNode(knight::dfa::ProgramState*) (/Users/shenjunjie/gits/knight/build/src/libknight-lib.dylib+0x59c6c)
 #4 0x00000001094d9bc4 knight::dfa::release_state(knight::dfa::ProgramState const*) (/Users/shenjunjie/gits/knight/build/src/libknight-lib.dylib+0x59bc4)
 #5 0x00000001043226c8 llvm::IntrusiveRefCntPtrInfo<knight::dfa::ProgramState const>::release(knight::dfa::ProgramState const*) (/Users/shenjunjie/gits/knight/build/bin/knight+0x10001a6c8)
 #6 0x00000001043226a0 llvm::IntrusiveRefCntPtr<knight::dfa::ProgramState const>::release() (/Users/shenjunjie/gits/knight/build/bin/knight+0x10001a6a0)
 #7 0x0000000109486e3c llvm::IntrusiveRefCntPtr<knight::dfa::ProgramState const>::~IntrusiveRefCntPtr() (/Users/shenjunjie/gits/knight/build/src/libknight-lib.dylib+0x6e3c)
 #8 0x0000000109486d80 llvm::IntrusiveRefCntPtr<knight::dfa::ProgramState const>::~IntrusiveRefCntPtr() (/Users/shenjunjie/gits/knight/build/src/libknight-lib.dylib+0x6d80)
 #9 0x00000001094994a0 knight::dfa::AnalysisContext::~AnalysisContext() (/Users/shenjunjie/gits/knight/build/src/libknight-lib.dylib+0x194a0)
#10 0x0000000109499470 knight::dfa::AnalysisContext::~AnalysisContext() (/Users/shenjunjie/gits/knight/build/src/libknight-lib.dylib+0x19470)
#11 0x0000000109499414 std::__1::default_delete<knight::dfa::AnalysisContext>::operator()[abi:ne180100](knight::dfa::AnalysisContext*) const (/Users/shenjunjie/gits/knight/build/src/libknight-lib.dylib+0x19414)
#12 0x0000000109499390 std::__1::unique_ptr<knight::dfa::AnalysisContext, std::__1::default_delete<knight::dfa::AnalysisContext>>::reset[abi:ne180100](knight::dfa::AnalysisContext*) (/Users/shenjunjie/gits/knight/build/src/libknight-lib.dylib+0x19390)
#13 0x0000000109499320 std::__1::unique_ptr<knight::dfa::AnalysisContext, std::__1::default_delete<knight::dfa::AnalysisContext>>::~unique_ptr[abi:ne180100]() (/Users/shenjunjie/gits/knight/build/src/libknight-lib.dylib+0x19320)
#14 0x0000000109487844 std::__1::unique_ptr<knight::dfa::AnalysisContext, std::__1::default_delete<knight::dfa::AnalysisContext>>::~unique_ptr[abi:ne180100]() (/Users/shenjunjie/gits/knight/build/src/libknight-lib.dylib+0x7844)
#15 0x00000001095382cc knight::dfa::AnalysisManager::~AnalysisManager() (/Users/shenjunjie/gits/knight/build/src/libknight-lib.dylib+0xb82cc)
#16 0x00000001095381f4 knight::dfa::AnalysisManager::~AnalysisManager() (/Users/shenjunjie/gits/knight/build/src/libknight-lib.dylib+0xb81f4)
#17 0x00000001095381c0 std::__1::default_delete<knight::dfa::AnalysisManager>::operator()[abi:ne180100](knight::dfa::AnalysisManager*) const (/Users/shenjunjie/gits/knight/build/src/libknight-lib.dylib+0xb81c0)
#18 0x0000000109538184 std::__1::unique_ptr<knight::dfa::AnalysisManager, std::__1::default_delete<knight::dfa::AnalysisManager>>::reset[abi:ne180100](knight::dfa::AnalysisManager*) (/Users/shenjunjie/gits/knight/build/src/libknight-lib.dylib+0xb8184)
#19 0x0000000109538114 std::__1::unique_ptr<knight::dfa::AnalysisManager, std::__1::default_delete<knight::dfa::AnalysisManager>>::~unique_ptr[abi:ne180100]() (/Users/shenjunjie/gits/knight/build/src/libknight-lib.dylib+0xb8114)
#20 0x0000000109532840 std::__1::unique_ptr<knight::dfa::AnalysisManager, std::__1::default_delete<knight::dfa::AnalysisManager>>::~unique_ptr[abi:ne180100]() (/Users/shenjunjie/gits/knight/build/src/libknight-lib.dylib+0xb2840)
#21 0x0000000109537434 knight::KnightASTConsumerFactory::~KnightASTConsumerFactory() (/Users/shenjunjie/gits/knight/build/src/libknight-lib.dylib+0xb7434)
#22 0x00000001095373f8 knight::KnightASTConsumerFactory::~KnightASTConsumerFactory() (/Users/shenjunjie/gits/knight/build/src/libknight-lib.dylib+0xb73f8)
#23 0x00000001095373c4 knight::(anonymous namespace)::KnightActionFactory::~KnightActionFactory() (/Users/shenjunjie/gits/knight/build/src/libknight-lib.dylib+0xb73c4)
#24 0x0000000109534154 knight::(anonymous namespace)::KnightActionFactory::~KnightActionFactory() (/Users/shenjunjie/gits/knight/build/src/libknight-lib.dylib+0xb4154)
#25 0x0000000109533c08 knight::KnightDriver::run() (/Users/shenjunjie/gits/knight/build/src/libknight-lib.dylib+0xb3c08)
#26 0x000000010430fa38 main (/Users/shenjunjie/gits/knight/build/bin/knight+0x100007a38)
#27 0x0000000188bcb154 
[1]    9589 segmentation fault  knight -checkers="*" --dump-cfg test/testcase/b.cpp

Incorrect Default Build Type in CMakeLists.txt

The CMakeLists.txt file specifies "Release" as the default build type in the following lines:

if(NOT CMAKE_BUILD_TYPE)
  set(CMAKE_BUILD_TYPE
    "Release"
    CACHE
    STRING
    "Build mode ('DebugSan' or 'Debug' or 'Release', default is 'Debug')"
    FORCE)
endif()

However, the comment indicates that the default should be 'Debug'. This discrepancy can lead to confusion and potentially unintended builds in the release mode when the user expects a debug build.

Steps to Reproduce:

1. Clone the repository.
2. Create a build directory and run cmake ...
3. Observe the default build type set in the generated CMakeCache.txt file.

Expected Behavior:
The default build type should be 'Debug' as indicated by the comment.

Actual Behavior:
The default build type is set to 'Release'.

Proposed Solution:
Update the CMakeLists.txt to set the default build type to 'Debug' to align with the comment.

if(NOT CMAKE_BUILD_TYPE)
  set(CMAKE_BUILD_TYPE
    "Debug"
    CACHE
    STRING
    "Build mode ('DebugSan' or 'Debug' or 'Release', default is 'Debug')"
    FORCE)
endif()

Additional Context:
Ensuring the default build type is correctly set to 'Debug' will help developers catch issues early during development and align with the documented behavior.

[Bug] Potential crash when using LLVM 18 or newer

The current version of the knight project has an issue when using LLVM 18 or newer versions. When building knight with the latest LLVM, it can result in a crash due to a known issue in LLVM's CommandLine library.

Description

The knight project is using LLVM's CommandLine library to handle command line options. However, there is a known issue in LLVM 18 and newer versions where the Option class can be registered more than once, leading to a crash.

This issue is described in the LLVM bug tracker: CommandLine Error: Option 'experimental-debuginfo-iterators' registered more than once!

Steps to Reproduce

1. Build LLVM 18 or newer from source.
2. Build the knight project using the newly built LLVM.
3. Run the knight tool.

The tool will crash with an error similar to:

CommandLine Error: Option 'experimental-debuginfo-iterators' registered more than once!
LLVM ERROR: inconsistency in registered CommandLine options
[1]    26042 abort

Impact

This issue makes it difficult for users to build and use the knight project with the latest LLVM versions, as it will result in a crash. This can severely limit the adoption and usability of the tool.

Proposed Solution

To fix this issue, the knight project should update the way it links against LLVM. Instead of linking against the LLVM static libraries, it should link against the LLVM dynamic library (libLLVM.so). This should resolve the issue with the CommandLine library.

The steps to update the knight project would be:

1. Modify the CMake scripts to allow linking against the LLVM dynamic library.
2. Update the installation script and documentation to recommend using the LLVM dynamic library for building knight.
3. Add a troubleshooting section in the documentation to address this issue and provide the solution.

Acceptance Criteria

• The knight project can be built and used without crashing when using LLVM 18 or newer versions.
• The documentation and installation scripts are updated to reflect the recommended way of building knight with the latest LLVM versions.
• The troubleshooting section in the documentation addresses the CommandLine issue and provides the solution.

Compilation Failure with Undefined References to LLVM and Clang Libraries

After attempting to compile the knight project, I encountered several undefined references errors related to LLVM and Clang libraries. This issue prevents the successful compilation and linking of the knight tool. It seems like the project configuration might not correctly specify the dependencies or the paths to the LLVM and Clang libraries are not properly resolved.

Steps to Reproduce:

1. Clone the knight project from the repository.
2. Follow the installation instructions provided in the README.md.
3. Run the build command: cmake --build .

Expected Behavior:

The knight project compiles successfully without any linker errors.

Actual Behavior:

Compilation fails with multiple errors similar to the following:

undefined reference to `llvm::sys::PrintStackTrace(llvm::raw_ostream&)'
undefined reference to `clang::FrontendOptions::FrontendOptions()'
...

Possible Solutions:

• Ensure that the paths to LLVM and Clang libraries and include directories are correctly specified in the CMakeLists.txt or the environment variables.
• Verify that the required LLVM and Clang libraries are installed and accessible.
• Consider adding detailed instructions in the README.md regarding setting up LLVM and Clang dependencies for the project.