>_ Documentation

Get Started with ApiPosture

Installation, CLI reference, configuration, and CI/CD integration.

Installation

ApiPosture is distributed as a .NET global tool. Install it with a single command:

dotnet tool install -g ApiPosture

Prerequisites

  • .NET 8.0 SDK or later
  • Windows, macOS, or Linux

Verify Installation

apiposture --version
ApiPosture 1.0.0

Update to Latest Version

dotnet tool update -g ApiPosture

Quick Start

Scan your ASP.NET Core API project in seconds:

# Navigate to your solution directory
cd ~/projects/MyWebApi
 
# Scan the API project
apiposture scan ./src/MyWebApi
 
✓ Scanned 47 files
✓ Found 156 endpoints
⚠ 3 critical findings
⚠ 7 high severity findings

ApiPosture uses Roslyn's syntax-only parsing, which means:

  • No compilation required - works with incomplete code
  • Fast - typical scans complete in under 2 seconds
  • No dependencies - doesn't need your NuGet packages

CLI Reference

scan

The main command to analyze your API project.

apiposture scan <path> [options]

Arguments

  • <path> - Path to the directory containing your C# source files

Options

Option Description Default
--output, -o Output format: terminal, json, markdown terminal
--fail-on Exit with non-zero code if severity found: critical, high, medium, low -
--exclude Glob patterns to exclude (can be used multiple times) -
--config Path to configuration file .apiposture.json
--no-color Disable colored output false
--verbose, -v Show detailed output false

Examples

# Basic scan
apiposture scan ./src/Api
 
# Output as JSON
apiposture scan ./src/Api --output json
 
# Fail CI if high severity issues found
apiposture scan ./src/Api --fail-on high
 
# Exclude test files
apiposture scan ./src --exclude "**/Tests/**"
 
# Save markdown report
apiposture scan ./src/Api --output markdown > report.md

Configuration

Create a .apiposture.json file in your project root for persistent configuration:

{
"exclude": [
"**/Tests/**",
"**/Migrations/**"
],
"rules": {
"AP005": {
"maxRoles": 4
},
"AP006": {
"allowedGenericRoles": ["Admin"]
},
"AP007": {
"sensitiveKeywords": [
"admin", "debug", "internal", "config", "secret"
]
}
},
"disabledRules": ["AP006"]
}

Configuration Options

  • exclude - Array of glob patterns to exclude from scanning
  • rules - Per-rule configuration overrides
  • disabledRules - Array of rule IDs to disable

Output Formats

Terminal (Default)

Human-readable colored output optimized for terminal viewing:

apiposture scan ./src --output terminal

JSON

Machine-readable output for integration with other tools:

apiposture scan ./src --output json > results.json

Markdown

Formatted report suitable for documentation or PR comments:

apiposture scan ./src --output markdown > report.md

CI/CD Integration

Integrate ApiPosture into your CI/CD pipeline to catch security issues before they reach production.

GitHub Actions

# .github/workflows/security.yml
name: API Security Scan
 
on: [push, pull_request]
 
jobs:
security-scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
 
- name: Setup .NET
uses: actions/setup-dotnet@v4
with:
dotnet-version: '8.0.x'
 
- name: Install ApiPosture
run: dotnet tool install -g ApiPosture
 
- name: Run Security Scan
run: apiposture scan ./src/Api --fail-on high

Azure DevOps

# azure-pipelines.yml
- task: DotNetCoreCLI@2
displayName: 'Install ApiPosture'
inputs:
command: 'custom'
custom: 'tool'
arguments: 'install -g ApiPosture'
 
- script: apiposture scan ./src/Api --fail-on high
displayName: 'API Security Scan'

GitLab CI

# .gitlab-ci.yml
security-scan:
image: mcr.microsoft.com/dotnet/sdk:8.0
script:
- dotnet tool install -g ApiPosture
- export PATH="$PATH:$HOME/.dotnet/tools"
- apiposture scan ./src/Api --fail-on high

Security Rules

ApiPosture includes 8 purpose-built security rules. See the Features page for detailed explanations of each rule.

Rule Category Severity Description
AP001 Exposure HIGH Unintentional Public Access
AP002 Exposure HIGH Anonymous Write Operations
AP003 Consistency MEDIUM Authorization Conflicts
AP004 Consistency CRITICAL Missing Auth on Writes
AP005 Privilege LOW Role Sprawl
AP006 Privilege LOW Weak Role Names
AP007 Surface MEDIUM Sensitive Routes Exposed
AP008 Surface HIGH Minimal API Gaps
>_ Need Help?

Questions or Feedback?

Open an issue on GitHub or reach out via our contact page.

Open an Issue Contact Us