# Technical Documentation: microsoft/ApplicationInspector

> ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/microsoft/ApplicationInspector)

### Overview (`README.md`)

# Introduction

 
[](https://www.nuget.org/packages/Microsoft.CST.ApplicationInspector.CLI/) 
[](https://www.nuget.org/packages/Microsoft.CST.ApplicationInspector.CLI/)

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](https://www.zdnet.com/article/microsoft-application-inspector-is-now-open-source-so-use-it-to-test-code-security/
), [SecurityWeek](https://www.securityweek.com/microsoft-introduces-free-source-code-analyzer)
, [CSOOnline](https://www.csoonline.com/article/3514732/microsoft-s-offers-application-inspector-to-probe-untrusted-open-source-code.html)
, [Linux.com/news](https://www.linux.com/news/microsoft-application-inspector-is-now-open-source-so-use-it-to-test-code-security/)
, [HelpNetSecurity](https://www.helpnetsecurity.com/2020/01/17/microsoft-application-inspector/
), Twitter and more and was first featured
on [Microsoft.com](https://www.microsoft.com/security/blog/2020/01/16/introducing-microsoft-application-inspector/).

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](https://github.com/microsoft/ApplicationInspector/wiki/3.4-Applies_to-(languages)) 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

### .NET Tool (recommended)

- Download and install the .NET 6 [SDK](https://dotnet.microsoft.com/download/)
- Run `dotnet tool install --global Microsoft.CST.ApplicationInspector.CLI`

See more in the [wiki](https://github.com/microsoft/ApplicationInspector/wiki/2.-NuGet-Support)

### Platform Dependent Binary

- Download Application Inspector by selecting the pre-built package for the operating system of choice shown under the
  Assets section
  of the [Releases](https://github.com/microsoft/ApplicationInspector/releases).

## Run Application Inspector

- 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](https://github.com/microsoft/ApplicationInspector/wiki/3.-Understanding-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](https://github.com/microsoft/ApplicationInspector/releases).

The C# library is available on NuGet
as [Microsoft.CST.ApplicationInspector.Commands](https://www.nuget.org/packages/Microsoft.CST.ApplicationInspector.Commands/)
.

The .NET Global Tool is available on NuGet
as [Microsoft.CST.ApplicationInspector.CLI](https://www.nuget.org/packages/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](https://github.com/microsoft/ApplicationInspector/blob/master/JustRunIt.md)
or [Build.md](https://github.com/microsoft/ApplicationInspector/blob/master/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:

### Command Help

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

### Analyze Command

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
For additional help on use of the console interface
see [CLI Usage](https://github.com/microsoft/ApplicationInspector/wiki/1.-CLI-Usage).

For help using the NuGet package
see [NuGet Support](https://github.com/microsoft/ApplicationInspector/wiki/2.-NuGet-Support)

# Build Instructions

See [build.md](https://github.com/microsoft/ApplicationInspector/blob/main/BUILD.md)

## Privacy

Usage of this application is governed by the [Microsoft Privacy Statement](https://go.microsoft.com/fwlink/?LinkId=521839).

---

### Overview (`AppInspector/rules/samples/README.md`)

# Application Inspector Sample Rules

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

## Files

### comprehensive_sample_rule.json

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

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

### Required Fields

- `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

- `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](#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

- `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

- `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

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

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

Two optional features let you go beyond that shape.

### Scoping a condition to one pattern

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.

```json
"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

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:

```json
"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

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.

```json
"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:

```json
"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

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

- [Rule Schema](../../../rule-schema-v1.json)
- [Application Inspector Wiki](https://github.com/microsoft/ApplicationInspector/wiki)

---

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