Skip to content

Latest commit

 

History

History
142 lines (96 loc) · 9.07 KB

checker.md

File metadata and controls

142 lines (96 loc) · 9.07 KB

Custom CoraxJava Rule Checker

Overview

This project is the CoraxJava Rule Checker module, which can implement multiple rule checks and compile them into a plugin form, to be loaded and executed by the CoraxJava Core Analysis Engine module.

It is often necessary to customize CoraxJava rule checkers, including several common scenarios, from simple to complex, and from shallow to deep customization:

  1. Coarse-grained adjustments to the CoraxJava rule checker module; such as enabling/disabling certain rule checks, adding already implemented rule checkers, and adding some data check properties to already implemented rule checkers.
  2. Fine-grained adjustments to the CoraxJava rule checker; such as modifying the source, sink, or modifying data transmission rules summary configuration of certain already implemented rule checkers.
  3. Adding new rules for checks, but using existing checkers as templates, with slight modifications to configurations and code to complete the check.
  4. Adding new rules for checks, but requiring completely custom development and implementation of their checkers.

Scenario One: Coarse-Grained Adjustment of the CoraxJava Rule Checker Module

Simply modify the yaml configuration file analysis-config/default-config.yml to achieve coarse-grained adjustments to the CoraxJava Rule Checker module.

For example, to enable/disable specific checkers, you can set enable to false in the following configuration:

- !<CheckerUnitOptionalConfig>
    name: "feysh-config-community:com.feysh.corax.config.community.checkers.httponly-cookie"
    enable: true
    options: null

To add options to a checker, including adding TaintTypes to the checker

 - !<CheckerUnitOptionalConfig>
    name: "feysh-config-community:com.feysh.corax.config.community.checkers.taint-checker"
    enable: true
    options: !<com.feysh.corax.config.community.checkers.taint-checker.Options>
      kind2Checker:
        "command-injection":
          checkTaintTypes:
          - !<GeneralTaintTypes> "ControlData"
          - !<GeneralTaintTypes> "CONTAINS_COMMAND_INJECT"
          taintTypeExcludes: []
          reportType: !<com.feysh.corax.config.community.CmdiChecker.CommandInjection> {}
          msgArgs: {}
          enable: true

For more information, refer to analysis-config/default-config.yml and subsequent explanations.

Scenario Two: Fine-Grained Adjustment of the CoraxJava Rule Checker

Commonly involves modifying the source, sink, summary, and other configurations of existing rule checkers.

Files with the suffix sources.json such as general.sources.json contain sources that are grouped together and categorized using kind, for example:

[
  {"kind":"remote","signature":"javax.servlet.ServletRequest: * getInputStream()","subtypes":false,"arg":"ReturnValue","provenance":"manual","ext":""},
  {"kind":"remote","signature":"javax.servlet.ServletRequest: * getParameter(String)","subtypes":false,"arg":"ReturnValue","provenance":"manual","ext":""},
  ...
]

Similarly, files with the suffix sinks.json such as community.sinks.json contain sinks that are grouped together and categorized using kind:

[
    {"kind":"command-injection","signature":"java.lang.Runtime: * load(String)","subtypes":false,"arg":"Argument[0]","provenance":"ai-manual","ext":""},
    {"kind":"command-injection","signature":"java.lang.Runtime: * loadLibrary(String)","subtypes":false,"arg":"Argument[0]","provenance":"ai-manual","ext":""},
    ...
]

Files with the suffix summaries.json, such as general.summaries.json, contain summaries related to the rules and configurations.

[
  {"signature":"java.lang.AbstractStringBuilder: * <init>(String)","subtypes":true,"argTo":"Argument[this]","propagate":"taint","argFrom":"Argument[0]","provenance":"manual","ext":""},
  {"signature":"java.lang.AbstractStringBuilder: * append(**)","subtypes":true,"argTo":"ReturnValue","propagate":"value","argFrom":"Argument[this]","provenance":"manual","ext":""}
  ...
]
  • signature can be in the format of matchSoot or in the format of matchSimpleSig.
  • subtypes indicates whether to handle overridden methods in subclasses (static methods are always false, interfaces are always true).
  • "propagate": "taint" means taint kinds propagation. After method execution, to and from may point to different objects. If they are different, then to has been tainted or affected, while from remains unaffected, unless there are alias relationships in the program.
  • "propagate": "value" means value propagation, where to and from point to the same object.
  • provenance is a reserved field and is not closely related to ext.

Scenario Three: Modification of CoraxJava Rule Checker

By modifying some code or parameters, you can customize the rule checker.

Developers can compare the types of vulnerabilities they want to detect with the rules already implemented in the community version and then proceed to implement similar rule codes. For example:

  1. Command injection rule checker is a typical Taint-type checker, which can be referenced for implementing injection issues (SSRF detection, SQL injection, XSS injection, path traversal, template injection, open redirection, etc.) and sensitive information leakage, both fall under the category of taint issues.
  2. The implementation of SQL injection rule checker includes not only classic Taint-type checking but also includes support for adapting MyBatis framework injection sink point checking.
  3. The Spring Response Body injection check for XSS vulnerability is implemented by dynamically checking sink points through matching corresponding Java annotations, similar to SQL injection checks in scenarios with hibernate.jpa Query annotations and ibatis Select annotations.
  4. The cookie attribute setting check mainly demonstrates API call sequence combination checks and detection of specific parameters, similar to PermissiveCors check.
  5. Detection of insecure TLS versions mainly involves specific API detection and constant parameter detection, similar to checks for cryptographic misuse, weak hash algorithms, cookie persistent maxAge, Ldap anonymous, etc.
  6. Omitted, can be found in other open source implementations in this project.

Scenario Four: Customization of CoraxJava Rule Checker

  1. Define Checker referring to IChecker (if it exists then proceed)

    1. Define Rule referring to IRule
    2. Define BugCategory IBugCategory
  2. Define CheckType referring to CheckType (if it exists then proceed)

    1. Define bug message referring to BugMessage
  3. Choose a CheckerUnit, based on the bugs and principles to be checked by the checker, choose a suitable Analysis, refer to CheckerUnit

    1. PreAnalysisUnit
    2. AIAnalysisUnit
  4. Once chosen, start writing the checker according to the requirements and corresponding check principles, and when calling ICheckPoint.report(checkType) or IOperatorFactory.check(boolExpr, checkType), pass in the CheckType from step two.

    If you need to check for some more direct bugs in your written checker, you can follow these two steps:

    1. Edit the AnalyzerConfigRegistry file and add the newly added checker registration in preAnalysisImpl or aiCheckerImpl.
    2. After adding it, you can run gradlew :corax-config-community:test --tests "com.feysh.corax.config.tests.ConfigValidate.validate", which can check for some checker writing errors and prompt for corrections.
  5. Go to corax-config-tests/normal/src/main/java/testcode and write corresponding non-compliant and compliant code to test and ensure analysis accuracy, refer to Unit Testing

  6. Run gradlew build to compile and package the final configuration build/analysis-config

  7. Follow Readme.md#Getting Started with Analysis to load the configuration and start analysis

  8. View the report sarif, if there are any false positives or missed reports, analyze the reasons and consider if corrections or optimizations are needed, refer to Result Output

For more detailed detection methods, you can refer to Detailed Explanation of Custom Rule Checker.