ApplicationInspector Documentation

Technical Documentation: microsoft/ApplicationInspector

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

Introduction

Microsoft Application Inspector is a software source code characterization tool that helps identify coding features of
first or third party software components based on well-known library/API calls and is helpful in security and
non-security use cases. It uses hundreds of rules and regex patterns to surface interesting characteristics of source
code to aid in determining what the software is or what it does from what file operations it uses, encryption,
shell operations, cloud API's, frameworks and more and has received industry attention as a new and valuable
contribution to OSS
on ZDNet, SecurityWeek
, CSOOnline
, Linux.com/news
, HelpNetSecurity, Twitter and more and was first featured
on Microsoft.com.

Application Inspector is different from traditional static analysis tools in that it doesn't attempt to identify "good"
or "bad" patterns; it simply reports what it finds against a set of over 400 rule patterns for feature detection
including features that impact security such as the use of cryptography and more. This can be extremely helpful in
reducing the time needed to determine what Open Source or other components do by examining the source directly rather
than trusting to limited documentation or recommendations.

The tool supports scanning various programming languages including C, C++, C#, Java, JavaScript, HTML, Python,
Objective-C, Go, Ruby, PowerShell
and more and can scan projects with
mixed language files. It supports generating results in HTML, JSON and text output formats with the default being an
HTML report similar to the one shown here.

Be sure to see our complete project wiki page https://Github.com/Microsoft/ApplicationInspector/wiki for additional
information and help.

Quick Start

Obtain Application Inspector Copy Chapter

.NET Tool (recommended) Copy Section

• Download and install the .NET 6 SDK
• Run dotnet tool install --global Microsoft.CST.ApplicationInspector.CLI

See more in the wiki

Platform Dependent Binary Copy Section

• Download Application Inspector by selecting the pre-built package for the operating system of choice shown under the
  Assets section
  of the Releases.

Run Application Inspector Copy Chapter

• Nuget Tool: appinspector analyze -s path/to/src.
• Platform Specific: applicationinspector.cli.exe analyze -s path/to/src

Goals

Microsoft Application Inspector helps you in securing your applications from start to deployment.

Design Choices - Enables you to choose which components meet your needs with a smaller footprint of unnecessary or
unknowns features for keeping your application attack surface smaller as well as help to verify expected ones i.e.
industry standard crypto only.

Identifying Feature Deltas - Detects changes between component versions which can be critical for detecting
injection of backdoors.

Automating Security Compliance Checks - Use to identify components with features that require additional security
scrutiny, approval or SDL compliance as part of your build pipeline or create a repository of metadata regarding all of
your enterprise application.

Contribute

We have a strong default starting base of Rules for feature detection. But there are many feature identification
patterns yet to be defined and we invite you to submit ideas on what you want to see or take a crack at defining a
few. This is a chance to literally impact the open source ecosystem helping provide a tool that everyone can use. See
the Rules section of the wiki for more.

Official Releases

Application Inspector is in GENERAL AUDIENCE release status. Your feedback is important to us. If you're interested in
contributing, please review the CONTRIBUTING.md.

Application Inspector is available as a command line tool or NuGet package and is supported on Windows, Linux, or MacOS.

Platform specific binaries of the ApplicationInspector CLI are available on our
GitHub releases page.

The C# library is available on NuGet
as Microsoft.CST.ApplicationInspector.Commands
.

The .NET Global Tool is available on NuGet
as Microsoft.CST.ApplicationInspector.CLI.

If you use the .NET Core version, you will need to have .NET 6.0 or later installed. See
the JustRunIt.md
or Build.md files for more.

CLI Usage Information

> appinspector --help
ApplicationInspector.CLI 1.8.4-beta+976ee3cdd1
c Microsoft Corporation. All rights reserved.

  analyze        Inspect source directory/file/compressed file (.tgz|zip)
                 against defined characteristics

  tagdiff        Compares unique tag values between two source paths

  exporttags     Export the list of tags associated with the specified rules.
                 Does not scan source code.

  verifyrules    Verify custom rules syntax is valid

  packrules      Combine multiple rule files into one file for ease in
                 distribution

  help           Display more information on a specific command.

  version        Display version information.

Examples: Copy Chapter

Command Help Copy Section

To get help for a specific command run appinspector <command> --help.

Analyze Command Copy Section

The Analyze Command is the workhorse of Application Inspector.

Simple Default Analyze

This will produce an output.html of the analysis in the current directory using default arguments and rules.

appinspector analyze -s path/to/files

Output Sarif

appinspector analyze -s path/to/files -f sarif -o output.sarif

Output Markdown

This will create a markdown output suitable for CI environments with a summary of key features.

appinspector analyze -s path/to/files -f markdown -o report.md

Excluding Files using Globs

This will create a json output named data.json of the analysis in the current directory, excluding all files in test
and .git folders using the provided glob patterns.

appinspector analyze -s path/to/files -o data.json -f json -g **/tests/**,**/.git/**

Additional Usage Information Copy Section

For additional help on use of the console interface
see CLI Usage.

For help using the NuGet package
see NuGet Support

Build Instructions

See build.md

Privacy Copy Chapter

Usage of this application is governed by the Microsoft Privacy Statement.

Overview (`AppInspector/rules/samples/README.md`) Copy Section

Application Inspector Sample Rules

This directory contains comprehensive sample rules that demonstrate all available fields and features for creating custom Application Inspector rules.

Files Copy Chapter

comprehensive_sample_rule.json Copy Section

A maximally specified sample rule file that demonstrates:

• All top-level rule fields: id, name, description, tags, severity, applies_to, does_not_apply_to, applies_to_file_regex, exclude_file_regex, depends_on_tags, overrides
• Pattern matching types: regex, regexword, string
• Pattern features: scopes, modifiers, confidence levels
• Conditions: same-file matching with both positive and negative conditions
• Self-testing: must-match and must-not-match arrays for validation
• Structured data queries: XPath for XML, JSONPath for JSON, YAMLPath for YAML
• Comments: Using _comment fields for documentation

Usage Copy Chapter

These sample rules are for reference and learning purposes. They demonstrate the full capabilities of the Application Inspector rule format.

To use these samples:

1. Copy and modify them for your specific detection needs
2. Adjust the patterns to match your target code constructs
3. Update the tags to fit your categorization scheme
4. Set appropriate severity levels
5. Add must-match/must-not-match test cases to validate your rules

Field Descriptions Copy Chapter

Required Fields Copy Section

• id: Unique identifier for the rule (e.g., "AI001234")
• name: Human-readable name describing what the rule detects
• tags: Array of categorization tags (at least one required)
• patterns: Array of search patterns (at least one required)

Optional Fields Copy Section

• description: Detailed description of what the rule detects
• severity: One of: critical, important, moderate, bestpractice, manualreview, unspecified (lowercase preferred; default: moderate)
• applies_to: Array of file extensions or language identifiers
• does_not_apply_to: Array of file extensions or language identifiers to exclude
• applies_to_file_regex: Array of regex patterns for files to include
• exclude_file_regex: Array of regex patterns for files to exclude
• depends_on_tags: Array of tags that must be present for this rule to apply
• overrides: Array of rule IDs that this rule supersedes
• conditions: Array of additional matching conditions
• expression: Boolean expression combining pattern and condition labels (see Expressions)
• must-match: Array of test strings that should match (for validation)
• must-not-match: Array of test strings that should not match (for validation)
• _comment: Optional comment for documentation

Pattern Fields Copy Section

• pattern: The regex/string pattern to search for (required)
• type: One of: regex (default), regexword, string, substring
• label: Name for this pattern, for use in expression (default: the pattern's index)
• conditions: Array of conditions that gate only this pattern's findings
• scopes: Array of: code, comment, all, html
• confidence: One of: high, medium, low, unspecified
• modifiers: Array of regex modifiers: i, m, s, x (or full names)
• xpaths: Array of XPath expressions for XML matching
• jsonpaths: Array of JSONPath expressions for JSON matching
• ymlpaths: Array of YAMLPath expressions for YAML matching
• _comment: Optional comment for documentation

Condition Fields Copy Section

• pattern: A pattern object (same structure as patterns array)
• search_in: Where to search - "finding-region(-offset,length)", "finding-only", "same-line", "same-file", "only-before", "only-after"
• negate_finding: Boolean - if true, the finding is invalid if this condition matches
• label: Name for this condition, for use in expression (default: the condition's clause index)
• applies_to: Array of languages this condition applies to (default: all)
• does_not_apply_to: Array of languages this condition does not apply to
• _comment: Optional comment for documentation

Expressions Copy Chapter

By default a rule matches when any pattern matches and every rule level condition holds:

(pattern0 OR pattern1 OR ...) AND condition0 AND condition1 ...

Two optional features let you go beyond that shape.

Scoping a condition to one pattern Copy Section

Declare the condition on the pattern it guards rather than at rule level. Other patterns are unaffected,
so they still report even when the condition excludes this pattern's finding.

"patterns": [
  {
    "pattern": "curl", "type": "substring", "label": "curl",
    "conditions": [
      {
        "pattern": { "pattern": "--tlsv1.3", "type": "substring" },
        "search_in": "same-line",
        "negate_finding": true
      }
    ]
  },
  { "pattern": "wget", "type": "substring", "label": "wget" }
]

Writing the expression yourself Copy Section

Set expression to combine labels with AND, OR, XOR, NAND, NOR and NOT. This makes
otherwise inexpressible rules possible, such as a disjunction of conditions or a negated conjunction:

"expression": "cookie AND NOT (secure AND httponly)"

That rule fires when either required flag is missing. Writing it as two negated conditions would
instead mean "neither flag is present", which stays silent on partially hardened code.

Every finding is judged against the expression on its own. A file containing one correctly hardened
cookie and one missing a flag reports the second, because the first satisfying secure AND httponly
says nothing about the second.

Because a finding originates from exactly one pattern, every other pattern label is false while
that finding is judged. An expression over pattern labels alone can therefore select which patterns
originate findings, but it cannot require sibling patterns to co-occur: a AND NOT b reports exactly
what a reports. Conditions add co-occurrence tests because they are evaluated against each finding
and can be true or false independently of it.

Requiring that two patterns both appear Copy Section

This is why verification rejects an expression that needs two pattern labels true at once, such as
a AND b. That is a normal-form requirement rather than a restriction on AND: a condition is a
pattern plus a search window, so a term that only has to co-occur is written as a same-file
condition instead.

"expression": "p AND ois",
"patterns": [
    { "pattern": "readObject", "type": "substring", "label": "p", "scopes": [ "code" ] }
],
"conditions": [
    { "pattern": { "pattern": "ObjectInputStream", "type": "substring", "scopes": [ "code" ] },
      "search_in": "same-file", "label": "ois" }
]

That reports each readObject, but only in a file that also contains ObjectInputStream.

To report the locations of both terms, declare each one twice, once as a pattern so it can
originate a finding and once as a same-file condition so it can constrain the other:

"expression": "(a OR b) AND ca AND cb"

with patterns a and b, and same-file conditions ca and cb carrying those same two patterns.
Every a and every b is then reported, but only in files that contain both.

Expressions have no operator precedence. They are evaluated strictly left to right, so
a OR b AND c means (a OR b) AND c, not a OR (b AND c). Always use parentheses to make
grouping explicit; rule verification rejects an expression that mixes operators at the same level
without them.

Other rules for expressions:

• Labels may not contain spaces or parentheses, and must be unique within the rule.
• Every label named in the expression must belong to a pattern or condition in the same rule.
• Attach parentheses to labels: (a OR b) is valid, ( a OR b ) is not.
• Parentheses must be balanced.
• A rule that sets expression must express negation with NOT rather than negate_finding.
• Conditions test captured pattern findings independently of label order in the expression. For example,
  c AND a and a AND c are equivalent when c is a condition and a is a pattern.

Best Practices Copy Chapter

1. Use lowercase for enums: severity, type, confidence, and scopes should use lowercase values
2. Populate optional fields: Only include optional fields like recommendation or _comment if they contain meaningful content
3. Test your rules: Always include must-match and must-not-match examples
4. Use appropriate severity: Choose severity levels that reflect the actual impact
5. Use specific patterns: Make patterns as specific as possible to reduce false positives
6. Document with comments: Use _comment fields to explain complex patterns or conditions
7. Parenthesise expressions: Expressions fold left to right with no precedence, so group explicitly

Related Documentation Copy Chapter

• Rule Schema
• Application Inspector Wiki

--- METRICS ---

• Files Extracted: 2
• Estimated Token Budget: ~4230 tokens
• Canonical Reference: https://codewiki.google/github.com/microsoft/ApplicationInspector