CFLint

A static code analysis tool for CFML.

License: BSD

Current Version: 1.5.x

Versions

See CHANGELOG.md for further information.

Project and library organization

CFLint is a project developed and worked on by volunteers. When logging issues please, be nice and considerate. We're here to help. We really appreciate fixes and improvements, so feel free to talk to us and/or provide pull requests.

/src/main contains the source code. Tests can be found in /src/test. CFLint relies heavily on the CFParser project as well as a bunch of third-party Java libraries.

The master branch is considered our stable codebase. Most of the development happens in the dev branch resp. local development branches for specific issues.

Building CFLint

1. Fork the repository into your account and clone or download the codebase as a zip-file.

2. Install the tooling of your choice and build via Gradle or Maven (deprecated). CFLint requires Java 8.

   a. Gradle: execute

    gradlew build
   

   in the cflint directory

   b. Maven: execute

    mvn clean install
   

   in the cflint directory

   Alternatively, import the CFLint codebase into the IDE of your choice and use its respectively Gradle/Maven integration. This should work out of the box for Eclipse and IntelliJ users.

Using CFLint - Quickstart Guide

Get the latest version from Maven Central or the CFLint GitHub release page or build the project.

If you want to use CFLint from within another Maven project, use:

<dependency>
    <groupId>com.github.cflint</groupId>
    <artifactId>CFLint</artifactId>
    <version>1.4.0</version>
</dependency>

Or always use the latest:

<dependency>
    <groupId>com.github.cflint</groupId>
    <artifactId>CFLint</artifactId>
    <version>LATEST</version>
</dependency>

With the binaries retrieved one or the other way, you can now use CFLint on the command line.

Use the "-all"-version of the jar-file

CFLint-1.5.0-all.jar

Scan a folder with the complete set of rules

java -jar CFLint-1.5.0-all.jar -folder <baseFolder>

Scan a file with the complete set of rules

java -jar CFLint-1.5.0-all.jar -file <fullPathToFile>

See command line parameters and help

java -jar CFLint-1.5.0-all.jar -help

User manual

Note: This is a work in progress, we're currently collating information from a variety of sources.

Introduction

The simplest options for executing CFLint is via the command line. CFLint currently has a UI mode (triggered by -ui on the command line) which will be removed by the latest for CFLint 2.0 - see Issue #316. If you rely on the UI mode, you're unfortunately on your own - no more work will go into this from here onwards.

Configuration

Alternatively to the command line, you can put .cflintrc files into certain directories. Configuring CFLint this way conceptually allows you to run specific rules in specific parts of your application.

CFLint currently supports JSON- and XML-based configuration. XML-based configuration is deprecated in CFLint 1.3.0 and will be removed in CFLint 2.0.

Rules

When CFLint executes, it scans and parses your code (using CFParser). The syntax tree is then being examined against a set of built-in rules.

In CFLint, those rules are called and implemented as plugins (they live in /src/main/java/com/cflint/plugins). By default, all rules will be used against your codebase. This is what a lot of people will do, but using configuration allows you to build a custom scenario to test your code against. See RULES.md for more information on rules and their meaning.

CFLint is opinionated and every release after 1.3.0 will never scan in directories starting with a . to prevent wasting time of hidden directories such as build configuration, module/library storage or version control information.

Global configuration

The default and global configuration file is /src/main/resources/cflint.definition.json. Common usage of CFLint usually does not require replacing this file.

Folder-based configuration

Putting a .cflintrc file into a directory allows you to specify certain rules that should be executed for this directory and its children. Additionally, you can specify a handful of other properties.

An example .cflintrc file is shown below:

{
    "rule": [ ],
    "excludes": [ ],
    "includes": [ {
        "code": "FUNCTION_HINT_MISSING"
    } ],
    "inheritParent": false,
    "parameters": { }
}

• rule allows you add a plugin for this folder that is not listed in the global configuration. See ruleImpl in cflint.definition.json for examples.

• excludes and includes allow you to specify an array of objects describing rules you want to be applied for this directory and its children. In the example above, the only rule to be checked for will be FUNCTION_HINT_MISSING.

• inheritParent configures if the rules set in the global or any parent configuration should be inherited as a base set of rules.

• parameters allows configuration of rules. See RULES.md for the parameters of each rule and their defaults. You must precede the parameter name with the rule name separated by a dot.

• Please note: inheritPlugins and output were marked deprecated in CFLint 1.2.0 and removed in 1.4.0. Plugin inheritance is now always treated as true since the team cannot see a use case in which it should be disabled. The output type can be controlled elsewhere, such as command-line flags.

We provide a schema with the deprecated properties excluded.

See Recipes for some usage examples of .cflintrc. Example files can be found by browsing the project test files.

Annotation-based configuration

Quite often there are scenarios in which you would generally want to run a certain set of rules against your code but in specific cases need to ignore an otherwise valid violation.

A common example are violations of CFQUERYPARAM_REQ that can't be fixed by applying <cfqueryparam> because your DB server doesn't allow params in certain positions (for instance in a SELECT something FROM #application.config.linkedServerName#.DefaultDatabase.dbo.Comment scenario). See Issue #282 for more examples.

CFLint offers an annotation-based configuration to deal with this and similar scenarios. Annotations can be placed on the component- or function-level in a CFC or inline with code.

Tag-based CFML

<!---
@CFLintIgnore SOMETHINGELSE,MISSING_VAR,ANOTHERTHINGTOIGNORE
--->

CFScript

Ignoring all rules on the current line:

//cflint ignore:line

Ignoring a specific rule (or a comma-separated list of rules) on the current line:

//cflint ignore:MISSING_VAR

Multiline ignore annotation:

/*
    @CFLintIgnore SOMETHINGELSE,MISSING_VAR,ANOTHERTHINGTOIGNORE
*/

Ignoring within SQL

Within SQL, you can also use

<!--- @CFLintIgnore CFQUERYPARAM_REQ --->

to ignore a rule violation on the next line.

Precedence of configuration settings

Configuration of which plugins are run and which rules are included starts with the global configuration and flows through the command line parameters, folder level rules, and down to the annotations within the source.

• global configuration
• custom configuration file (-configfile, we do not encourage this option to be used in day-to-day operations of CFLint)
• rule groups (-rulegroups, default behavior is --rulegroups !Experimental)
• includes/excludes from the command line (-includeRule and -excludeRule)
• .cflintrc - folder level configuration, mostly for including/excluding specific messages
• annotations - explicitly exclude messages in the source code at the tag or line level.

The configuration rule that is closest to the rule is the one that takes effect.

• If an annotation excludes a message, it will not fire regardless of any configuration above it.
• If you exclude a rule at the command line level, but a .cflintrc adds it back in, it will fire for source files in that part of the source tree.
• If you are passing in multiple parameters at the command line level, in Windows Powershell the parameters must be included in "double quotes", e.g. -includeRule "MISSING_VAR,CFQUERYPARAM_REQ"

Creating reports

CFLint supports a variety of reporting and output options that you can control via command-line flags. Beyond the targeted output formats of Text, XML, JSON or HTML you can also run CFLint with options for quiet, verbose and debug output.

If no targeted output format is specified at all, CFLint will default to creating an HTML report in the file cflint-result.html.

Execution modes

You can force CFLint's output behavior to stdout and stderr by specifying options for quiet, verbose and debug. If you do not specify eit