-
Notifications
You must be signed in to change notification settings - Fork 353
3. Understanding Rules
Rules in Application Inspector are fairly simple, relative to other analysis engines. They are files that represent one or more individual search patterns for feature detection and associate to a rule name and tags for identifying the feature in systematic but friendly terms. We've identified a large set of default rules to start with.
Rule files are in JSON format, and consist of a high level Rule object, that in turn contains an array of one or more Pattern object (which defines the regular expression used for a match), and optionally contains arrays of one or more Condition objects (additional patterns that also need to be met). They are read from disk when the application first starts.
The default rules can be found in this Github repo under AppInspector/rules/default. Note the Build command now packages the default set into a single file which is embedded in the ApplicationInspector.Commands.dll for ease in distributing with our NuGet package. To modify the default ruleset, you would need to download the project source, modify them as needed and rebuild the solution which will automatically verify and repackage them.
Application Inspector rules are organized into files by topic for convenience in locating e.g. cryptography, data, operating system integration etc., and then by sub-area. In some cases, it makes sense to organize by programming language, but we'd prefer to keep that to a minimum and just specify the language where needed.
We will most likely avoid changing default rule ID's very often and have numbered them with spacing to allow for insertion of new rules between existing ones for co-location etc. but a better choice might be to use the tags associated with a rule as something that we will try to keep stable. The id identifiers are a means of uniquely identifying a rule since a given tag may be associated to more than one rule.
You can modify the default set of rules as needed or even add your own. ID's must be unique if you are adding your own or will fail to verify with an error notice. They are not compiled and may be modified on disk. We suggest to use the VerifyRules command to ensure they are ready to be run during the Analyze and other commands.
Rules may be applied to a specific set of programming languages for maintaining optimum performance to avoid searching for patterns in files needlessly or against all files types for patterns that are general. In many cases an pattern is applicable across all languages.
Each Application Inspector rule must have a unique identifier. Technically, this is opaque (just a string), and isn't limited by size or structure. However, for readability and consistency, we'll use the following scheme.
All built-in Application Inspector rules start with AI. Currently, the next digit is 0 for all rules, but we
reserve digits 0-4 for built-in rules. If you write your own, please either choose a different first digit
(AI512345) or a different prefix altogether (FOO123456).
There are a lot of patterns yet to be defined and we're continuing to add and improve them. Submit ideas you have for missing value-add features that could be helpful or submit a PR. For people who learn by looking at real world examples, looking at the default set is a good place to start.