Skip to content

Commit ed323d1

Browse files
tgauthtgauth
authored
Add AttackSurfaceAnalyzer Scripts (#818)
* add Travis' ASA scripts from PowerShell repo * remove msi from files * tweaks for OpenSSH * address copilot feedback
1 parent 56d9a65 commit ed323d1

3 files changed

Lines changed: 1253 additions & 0 deletions

File tree

‎contrib/win32/tools/AttackSurfaceAnalyzer/README.md‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
# Attack Surface Analyzer Testing
2+
3+
This directory contains tools for running Attack Surface Analyzer (ASA) tests on OpenSSH MSI installations directly on Windows with PowerShell 7 and .NET 9 SDK installed.
4+
5+
## Overview
6+
7+
Attack Surface Analyzer is a Microsoft tool that helps analyze changes to a system's attack surface. These scripts allow you to run ASA tests directly on Windows to analyze what changes when OpenSSH is installed.
8+
9+
## Files
10+
11+
- **Run-AttackSurfaceAnalyzer.ps1** - PowerShell script to run ASA tests with official MSIs
12+
- **Summarize-AsaResults.ps1** - PowerShell script to analyze and summarize ASA results
13+
- **README.md** - This documentation file
14+
15+
## Prerequisites
16+
17+
- Windows 10/11 or Windows Server
18+
- PowerShell 7
19+
- .NET 9 SDK
20+
- **An official signed OpenSSH MSI file** from a released build
21+
22+
### MSI Requirements
23+
24+
**Important:** This tool now requires an official, digitally signed OpenSSH MSI from Microsoft releases:
25+
26+
- **Must be signed** by Microsoft Corporation
27+
- **Must be from an official release** (downloaded from [OpenSSH Releases](https://github.com/PowerShell/Win32-OpenSSH/releases))
28+
- **Local builds are not supported** - unsigned or development MSIs will be rejected
29+
- The script automatically verifies the digital signature before proceeding
30+
31+
**Where to get official MSIs:**
32+
33+
- Download from: https://github.com/PowerShell/Win32-OpenSSH/releases
34+
- Look for files like: `OpenSSH-Win64-v10.x.x.x.msi`
35+
36+
## Quick Start
37+
38+
### Option 1: Using the PowerShell Script (Recommended)
39+
40+
The script requires an official signed OpenSSH MSI file:
41+
42+
```powershell
43+
# Run ASA test with official MSI (MsiPath is required)
44+
.contrib\win32\tools\AttackSurfaceAnalyzer\Run-AttackSurfaceAnalyzer.ps1 -MsiPath "C:\path\to\OpenSSH-Win64-v10.0.0.0.msi"
45+
46+
# Specify custom output directory for results
47+
.contrib\win32\tools\AttackSurfaceAnalyzer\Run-AttackSurfaceAnalyzer.ps1 -MsiPath ".\OpenSSH-Win64-v10.0.0.0.msi" -OutputPath "C:\asa-results"
48+
49+
# Keep the temporary work directory for debugging
50+
.\tools\AttackSurfaceAnalyzer\Run-AttackSurfaceAnalyzer.ps1 -MsiPath ".\OpenSSH-Win64-v10.0.0.0.msi" -KeepWorkDirectory
51+
```
52+
53+
The script will:
54+
55+
1. **Verify MSI signature** - Ensures the MSI is officially signed by Microsoft Corporation
56+
1. Install the Attack Surface Analyzer
57+
1. Start the Attack Surface Analyzer
58+
1. Take a baseline snapshot
59+
1. Install the OpenSSH MSI
60+
1. Take a post-installation snapshot
61+
1. Export comparison results
62+
1. Copy results back to your specified output directory
63+
64+
**Security Note:** The script will reject any MSI that is not digitally signed by Microsoft Corporation to ensure analysis is performed only on official releases.
65+
66+
## Output Files
67+
68+
The test will generate output files in the `./asa-results/` directory (or your specified `-OutputPath`):
69+
70+
- **`asa.sqlite`** - SQLite database with full analysis data (primary result file)
71+
- **`install.log`** - MSI installation log file
72+
- **`*_summary.json.txt`** - Summary of detected changes (if generated)
73+
- **`*_results.json.txt`** - Detailed results in JSON format (if generated)
74+
- **`*.sarif`** - SARIF format results (if generated, can be viewed in VS Code)
75+
76+
## Analyzing Results
77+
78+
### Using the Summary Script (Recommended)
79+
80+
Use the included summary script to get a comprehensive analysis:
81+
82+
```powershell
83+
# Basic summary of ASA results
84+
.contrib\win32\tools\AttackSurfaceAnalyzer\Summarize-AsaResults.ps1
85+
86+
# Detailed analysis with rule breakdowns
87+
.contrib\win32\tools\AttackSurfaceAnalyzer\Summarize-AsaResults.ps1 -ShowDetails
88+
89+
# Analyze results from a specific location
90+
.contrib\win32\tools\AttackSurfaceAnalyzer\Summarize-AsaResults.ps1 -Path "C:\custom\path\asa-results.json" -ShowDetails
91+
```
92+
93+
The summary script provides:
94+
95+
- **Overall statistics** - Total findings, analysis levels, category breakdowns
96+
- **Rule analysis** - Which security rules were triggered and how often
97+
- **File analysis** - Detailed breakdown of file-related security issues by rule type
98+
- **Category cross-reference** - Shows which rules affect which categories
99+
100+
### Using VS Code
101+
102+
The SARIF files can be opened directly in VS Code with the SARIF Viewer extension to see a formatted view of the findings.
103+
104+
### Using PowerShell
105+
106+
```powershell
107+
# Read the JSON results directly
108+
$results = Get-Content "asa-results\asa-results.json" | ConvertFrom-Json
109+
$results.Results.FILE_CREATED.Count # Number of files created
110+
111+
# Query the SQLite database (requires SQLite tools)
112+
# Example: List all file changes
113+
# sqlite3 asa.sqlite "SELECT * FROM file_system WHERE change_type != 'NONE'"
114+
```
115+
116+
## Troubleshooting
117+
118+
### MSI Signature Verification Fails
119+
120+
If you get signature verification errors:
121+
122+
- **Ensure you're using an official MSI** from [OpenSSH Releases](https://github.com/PowerShell/Win32-OpenSSH/releases)
123+
- **Do not use local builds** - only signed release MSIs are supported
124+
- **Check certificate validity** - very old MSIs may have expired certificates
125+
- **Verify file integrity** - redownload the MSI if it may be corrupted
126+
127+
### No Results Generated
128+
129+
- Check the install.log file for MSI installation errors
130+
- Run with `-KeepWorkDirectory` to inspect the temporary work directory
131+
- Verify the MSI file is valid and not corrupted
132+
133+
## Advanced Usage
134+
135+
### Parameters
136+
137+
The `Run-AttackSurfaceAnalyzer.ps1` script supports these parameters:
138+
139+
- **`-MsiPath`** (Required) - Path to the official signed OpenSSH MSI file
140+
- **`-WorkingDirectory`** (Optional) - Directory for MSI, if not provided (defaults to current directory)
141+
- **`-OutputDirectory`** (Optional) - Directory for results (defaults to `./asa-results`)
142+
- **`-AsaVersion`** (Optional) - ASA Tool Version (defaults to "2.3.328")
143+
- **`-SkipAsaInstall** (Optional) - Switch to skip ASA Tool install (defaults to false)
144+
- **`-KeepInstallation** (Optional) - Switch to skip MSI uninstall, recommended for debugging only (defaults to false)
145+
146+
### Debugging
147+
148+
To debug issues, keep the MSI install and examine the files:
149+
150+
```powershell
151+
.contrib\win32\tools\AttackSurfaceAnalyzer\Run-AttackSurfaceAnalyzer.ps1 -KeepInstallation
152+
153+
# The script will print the work directory path
154+
# You can then examine:
155+
# - C:\Program Files\OpenSSH - install directory
156+
# - install.log - MSI installation log
157+
# - Any other generated files
158+
```
159+
160+
## Integration with CI/CD
161+
162+
These tools were extracted from the GitHub Actions workflow to allow local testing. If you need to integrate ASA testing back into a CI/CD pipeline, you can use the PowerShell script directly in your pipeline
163+
164+
## More Information
165+
166+
- [Attack Surface Analyzer on GitHub](https://github.com/microsoft/AttackSurfaceAnalyzer)
167+
- [SARIF Documentation](https://sarifweb.azurewebsites.net/)

0 commit comments

Comments
 (0)