STRLCPY/win32-app-isolation

Acpdocs (#3)

* Content without examples.

* finalized with images.

* fix image scoping.

* nit.

* proper code blocks.

---------

Co-authored-by: Matheus Cruz Correia de Carvalho Souza <[email protected]>

macruzco committed with GitHub 12 months ago

0577c63b

1 parent 1fb2f491

Total 12 files Show one by one

■ ■ ■ ■ ■ ■

docs/profiler/application-capability-profiler.md

1	+	# Application Capability Profiler (ACP)
2	+
3	+	## Overview
4	+
5	+	Packaged applications may need to access resources outside of the sandbox. Examples of such resources include user files, pictures, registry items, camera, location, and microphone, among others. [Capability declaration](https://learn.microsoft.com/en-us/windows/uwp/packaging/app-capability-declarations) allows sandboxed applications to access some of those resources. Declarations are made in the sandboxed application's package manifest. See [msix-packaging-tool](https://github.com/microsoft/win32-app-isolation/blob/main/docs/packaging/msix-packaging-tool.md) for reference.
6	+
7	+	Application Capability Profiler is a set of tools that help identify what capabilities may need to be declared by an application package, so it's granted the resource access it needs. Furthermore, it provides useful diagnostic information on failed access attempts by the application package.
8	+
9	+	## Profiling step 0: set up the target system for profiling
10	+
11	+	#### 1. Ensure administrator privilege to the target Windows system is held.
12	+
13	+	#### 2. Enable developer mode on the target system. Settings > Privacy & security > For developers
14	+
15	+	#### 3. Install PowerShell 7
16	+
17	+	See [Installing PowerShell on Windows](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows?view=powershell-7.3) for instructions.
18	+
19	+	#### 4. Install Windows Performance Recorder (WPR) if not already installed and add it to PATH.
20	+
21	+	See [Windows Performance Recorder](https://learn.microsoft.com/en-us/windows-hardware/test/wpt/windows-performance-recorder) for instructions.
22	+
23	+	```PowerShell
24	+	Get-Command wpr
25	+	```
26	+
27	+	![image](https://github.com/microsoft/win32-app-isolation/blob/main/docs/profiler/images/acp-doc-get-command-wpr-output.png)
28	+
29	+	#### 5. Download the Application Capability Profiler archive and extract it to a convenient path.
30	+
31	+	[Download ACP]().
32	+
33	+	#### 6. Follow the instructions on [msix-packaging-tool](https://github.com/microsoft/win32-app-isolation/blob/main/docs/packaging/msix-packaging-tool.md) to package the application and install it on the target system.
34	+
35	+	#### 7. Obtain the target application package manifest (recommended) and/or the target application package full name.
36	+
37	+	1. (Recommended) Obtain the target application package manifest. The easiest way to do this is to open it using the [MSIX packaging tool](https://github.com/microsoft/win32-app-isolation/blob/main/docs/packaging/msix-packaging-tool.md) and save a copy of the manifest to a convenient path.
38	+
39	+	![image](https://github.com/microsoft/win32-app-isolation/blob/main/docs/profiler/images/acp-doc-manifest-open-via-mpt.png)
40	+	![image](https://github.com/microsoft/win32-app-isolation/blob/main/docs/profiler/images/acp-doc-manifest-save-as.png)
41	+	![image](https://github.com/microsoft/win32-app-isolation/blob/main/docs/profiler/images/acp-doc-manifest-newname-save-as.png)
42	+
43	+	2. Obtain the application package full name.
44	+
45	+	```PowerShell
46	+	Get-AppxPackage \| where-object {$_.name -like 'Test-AppSilo'}
47	+	```
48	+
49	+	![image](https://github.com/microsoft/win32-app-isolation/blob/main/docs/profiler/images/acp-doc-get-appxpackage-output.png)
50	+
51	+	#### 8. (Optional) Install the Windows Performance Analyzer.
52	+
53	+	See [Windows Performance Analyzer](https://learn.microsoft.com/en-us/windows-hardware/test/wpt/windows-performance-analyzer) for instructions. This is not required for profiling but may be helpful in visualizing some of the data captured and output by ACP.
54	+
55	+	## Profiling step 1: import the PowerShell module
56	+
57	+	In administrator PowerShell 7:
58	+
59	+	```PowerShell
60	+	Import-Module Microsoft.Windows.Win32Isolation.ApplicationCapabilityProfiler.dll
61	+	```
62	+
63	+	## Profiling step 2: Start-Profiling
64	+
65	+	The Start-Profiling cmdlet takes the path to the target application package manifest or the full name of the application package.
66	+	Start-Profiling will instrument the target application package for trace logging and enable a trace logging provider for access attempts made by the target application package.
67	+	Start-Profiling requires administrator privileges and that Developer Mode be enabled.
68	+
69	+	```PowerShell
70	+	Start-Profiling -ManifestPath TestAppSilo-AppXManifest.xml
71	+	```
72	+
73	+	![image](https://github.com/microsoft/win32-app-isolation/blob/main/docs/profiler/images/acp-doc-start-profiling-output.png)
74	+
75	+	## Profiling step 3: run the application scenarios
76	+
77	+	In this step, it is important that all the critical application scenarios are run. Profiling results are as comprehensive as the scenarios run at this step. The more application scenarios are exercised, the larger and more complete the amount of data captured by the trace logging session started above.
78	+
79	+	## Profiling step 4: Stop-Profiling
80	+
81	+	The Stop-Profiling cmdlet stops an access attempt trace logging session that has been started and takes away the instrumentation for any application packages that had been instrumented for trace logging.
82	+	Stop-Profiling takes an optional trace path parameter that controls the path used for the output Event Trace Log (.etl) file. <current_directory>\trace.etl by default.
83	+	Stop-Profiling requires administrator privileges and that Developer Mode be enabled.
84	+
85	+	```PowerShell
86	+	Stop-Profiling
87	+	```
88	+
89	+	![image](https://github.com/microsoft/win32-app-isolation/blob/main/docs/profiler/images/acp-doc-stop-profiling-output.png)
90	+
91	+	## Profiling step 5: Get-ProfilingResults
92	+
93	+	The Get-ProfilingResults cmdlet parses the trace file obtained from the steps above and finds the capabilities the application package(s) identified in the trace require. It outputs capabilities and information for every application package identified in the trace, unless filtering to a specific package is specified.
94	+
95	+	Get-ProfilingResults takes in the path to the trace file to parse. If none is provided, Get-ProfilingResults will attempt to Stop-Profiling to obtain a trace to parse.
96	+	Get-ProfilingResults optionally takes a path to a target application manifest. If information in the parsed trace can be attributed to the target application package manifest, the file is edited directly with the output capabilities. Otherwise, a copy of the manifest is made for each of the packages identified in the trace and their identified capabilities.
97	+
98	+	```PowerShell
99	+	Get-ProfilingResults -EtlFilePaths trace.etl -ManifestPath TestAppSilo-AppXManifest.xml
100	+	```
101	+
102	+	![image](https://github.com/microsoft/win32-app-isolation/blob/main/docs/profiler/images/acp-doc-get-profilingresults-output.png)
103	+
104	+	## Profiling step 6: repackaging
105	+
106	+	1. Include the newly identified capabilities in the target application package manifest (Get-ProfilingResults will edit the manifest directly if provided).
107	+	2. Follow instructions in [msix-packaging-tool](https://github.com/microsoft/win32-app-isolation/blob/main/docs/packaging/msix-packaging-tool.md) to repackage the target application with the new capabilities, and reinstall it.
108	+
109	+	## Helper cmdlets
110	+
111	+	The Merge-ProfilingResults cmdlet can be used to merge the output from multiple runs of Get-ProfilingResults.
112	+
113	+	## Interpreting Get-ProfilingResults output
114	+
115	+	1. Manifest-formatted capabilities
116	+
117	+	If the user provides a manifest to be edited under the -ManifestPath option and if the package to which the manifest pertains is identified in the input trace, Get-ProfilingResults will edit the manifest file directly to include the capabilities identified in the trace for the package. Otherwise, for each package identified in the trace file, Get-ProflingResults will output a file named <package full name>\<manifest name>.xml containing the <Capabilities> element with the capabilities identified in the trace for the corresponding package.
118	+
119	+	Note: there are two special kinds of capabilities Get-ProfilingResults may identify. These are flagged with XML comments in the output manifest.
120	+	* Privacy-sensitive capabilities: these capabilities protect privacy-sensitive resources such as camera, location, and microphone. These capabilities must be declared if the application package requires access to these resources. However, capability declaration alone may not be sufficient to ensure application access to the target privacy-sensitive resource. In privacy settings, the user can still grant or deny resource access to the application.
121	+	* Prompting capability: Get-ProfilingResults will output this capability in "commented-out" form when it identifies that the prompting capability may apply to an application package. If declared in ("uncommented" from) the package manifest, the application is opted into fallback prompting. User prompts will be issued every time the application hits access denied to a prompting-eligible resource. This gives the user a chance to explicitly grant or deny access to the resource. Fallback prompting can be intrusive and weaken the sandbox, so it should be used with caution, preferably only when required for critical application scenarios.
122	+
123	+	2. AccessAttemptRecords.csv
124	+
125	+	This is a comma separated values file containing detailed diagnostic information on parsed trace events and each failed access attempt logged for the application package.
126	+
127	+	3. summary.txt
128	+
129	+	This is a summary of all runs of Get-ProfilingResults. Each run appends to this file. -SummaryOutputPath can be used to control this filepath.
130	+
131	+	The summary contains the inputs parsed, target application packages and executables, identified capabilities, edited manifest contents and a summarized list of all the resources that the application package attempted to access but for which no capabilities were identified. Note that it may be that the target application will be unable to access these resources when packaged.
132	+
133	+	4. README.txt
134	+
135	+	Output guide for all runs of Get-ProfilingResults. Each run appends to this file.
136	+
137	+	README brings information on the input parsed, target application package, files output and their paths, as well as troubleshooting guide.
138	+
139	+	## Stack Tracing - ACP-StackTrace.wpaProfile
140	+
141	+	The ACP archive contains a file named ACP-StackTrace.wpaProfile. This is a profile for Windows Performance Analyzer (WPA). It enables stack trace visualization for the event trace log file captured by Stop-Profiling. It breaks down access attempts, their target, and the stack that issued the attempt. This enables a more complete understanding of the reasons why the target application is not able to access certain resources.
142	+
143	+	To visualize access attempt stacks captured by Stop-Profiling in "trace.etl":
144	+	1. Open trace.etl in WPA.
145	+	2. Configure WPA Symbol paths to point to the application symbols and the Microsoft public symbol server.
146	+
147	+	![image](https://github.com/microsoft/win32-app-isolation/blob/main/docs/profiler/images/acp-doc-wpa-configure-symbols.png)
148	+
149	+	3. Load symbols.
150	+	4. Apply the ACP-StackTrace.wpaProfile to bring up the access attempt stack visualization.
151	+
152	+	![image](https://github.com/microsoft/win32-app-isolation/blob/main/docs/profiler/images/acp-doc-wpa-applyprofile.png)
153	+	![image](https://github.com/microsoft/win32-app-isolation/blob/main/docs/profiler/images/acp-doc-wpa-stack-analysis.png)
154	+
155	+	See [Windows Performance Analyzer](https://learn.microsoft.com/en-us/windows-hardware/test/wpt/windows-performance-analyzer) for details.

docs/profiler/images/acp-doc-get-appxpackage-output.png
docs/profiler/images/acp-doc-get-command-wpr-output.png
docs/profiler/images/acp-doc-get-profilingresults-output.png
docs/profiler/images/acp-doc-manifest-newname-save-as.png
docs/profiler/images/acp-doc-manifest-open-via-mpt.png
docs/profiler/images/acp-doc-manifest-save-as.png
docs/profiler/images/acp-doc-start-profiling-output.png
docs/profiler/images/acp-doc-stop-profiling-output.png
docs/profiler/images/acp-doc-wpa-applyprofile.png
docs/profiler/images/acp-doc-wpa-configure-symbols.png
docs/profiler/images/acp-doc-wpa-stack-analysis.png