Skip to content

Commit a826455

Browse files
author
Jill Grant
authored
Merge pull request #289784 from karengu0/velma-docs-nov
Velma docs Nov
2 parents f22c90b + 61a095f commit a826455

21 files changed

+283
-37
lines changed

articles/defender-for-iot/device-builders/release-notes.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ ms.topic: conceptual
55
ms.date: 04/17/2024
66
---
77

8-
# What's new
8+
# What's new in Microsoft Defender for IoT
99

1010
[!INCLUDE [Banner for top of topics](../includes/banner.md)]
1111

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
title: Use service principals to automate workflows in Firmware analysis
3+
description: Learn about how to use service principals to automate workflows for Firmware Analysis.
4+
author: karengu0
5+
ms.author: karenguo
6+
ms.topic: conceptual
7+
ms.date: 11/04/2024
8+
---
9+
10+
# How to Use Service Principals to Automate Workflows in Firmware analysis
11+
12+
Many users of the firmware analysis service may need to automate their workflow. The command `az login` creates an interactive login experience with two-factor authentication that makes it difficult for users to fully automate their workflow. A service principal [Apps & service principals in Microsoft Entra ID](/entra/identity-platform/app-objects-and-service-principals) is a secure identity with proper permissions that authenticates to Azure in the command line without requiring two-factor authentication or an interactive log-in. This article explains how to create a service principal and use it to interact with the firmware analysis service. For more information on creating service principals, visit [Create Azure service principals using the Azure CLI](/cli/azure/azure-cli-sp-tutorial-1#create-a-service-principal). To authenticate securely, we recommend creating a service principal and authenticating using certificates. To learn more, visit [Create a service principal containing a certificate using Azure CLI](/cli/azure/azure-cli-sp-tutorial-3).
13+
14+
1. Log in to your Azure account using the portal.
15+
16+
2. Navigate to your subscription and assign yourself `User Access Administrator` or `Role Based Access Control Administrator` permissions, or higher, in your subscription. This gives you permission to create a service principal.
17+
18+
3. Navigate to your command line
19+
20+
1. Log in, specifying the tenant ID during login
21+
22+
```azurecli
23+
az login --tenant <TENANT_ID>
24+
```
25+
26+
3. Switch to your subscription where you have proper permissions to create a service principal
27+
28+
```azurecli
29+
az account set --subscription <SUBSCRIPTION_ID>
30+
```
31+
32+
5. Create service principal, assigning it the proper permissions at the proper scope. We recommend assigning your service principal the Firmware Analysis Admin role at the Subscription level.
33+
34+
```azurecli
35+
az ad sp create-for-rbac --name <SERVICE_PRINCIPAL_NAME> --role "Firmware Analysis Admin" --scopes /subscriptions/<SUBSCRIPTION_ID>
36+
```
37+
38+
4. Note down your service principal’s client ID (“`appId`”), tenant ID (“`tenant`”), and secret (“`password`”) in a safe place. You’ll need this for the next step.
39+
40+
5. Log in to your service principal
41+
42+
```azurecli
43+
az login --service-principal --username $clientID --password $secret --tenant $tenantID
44+
```
45+
46+
6. Once logged in, refer to the following Quickstarts for scripts to interact with the Firmware analysis service via Azure PowerShell, Azure CLI, or Python:
47+
- [Upload firmware using Azure CLI](quickstart-upload-firmware-using-azure-command-line-interface.md)
48+
- [Upload firmware using Azure PowerShell](quickstart-upload-firmware-using-powershell.md)
49+
- [Upload firmware using Python](quickstart-upload-firmware-using-python.md)
50+
51+

articles/firmware-analysis/firmware-analysis-faq.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ ms.date: 01/10/2024
99
---
1010

1111
# Frequently asked questions about Firmware analysis
12-
This article addresses frequent questions about Firmware analysis.
12+
This article addresses frequent questions about Firmware analysis.
1313

1414
[Firmware analysis](./overview-firmware-analysis.md) is a tool that analyzes firmware images and provides an understanding of security vulnerabilities in the firmware images.
1515

@@ -39,6 +39,7 @@ Firmware analysis supports unencrypted images that contain file systems with emb
3939
* POSIX tarball archive
4040
* UBI erase count header
4141
* UBI file system superblock node
42+
* UEFI file system
4243
* xz compressed data
4344
* YAFFS filesystem, big endian
4445
* YAFFS filesystem, little endian
Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
---
2+
title: Interpreting extractor paths from SBOM view in Firmware analysis
3+
description: Learn how to interpret extractor paths from the SBOM view in Firmware analysis results.
4+
author: karengu0
5+
ms.author: karenguo
6+
ms.topic: conceptual
7+
ms.date: 11/04/2024
8+
---
9+
10+
# Overview of How Firmware Images are Structured
11+
12+
A firmware image is a collection of files and file systems containing software that operates hardware. Often, it includes compressed files, executables, and system files. These file systems may or may not include other file systems within each file. For example, a firmware image that’s a .zip file may include individual files such as executables within it but may also include other compressed file systems, such as a SquashFS file. You can visualize it like the following:
13+
14+
:::image type="content" source="media/extractor-paths/file-systems.png" alt-text="Screenshot of how the file system of a firmware image might look like." lightbox="media/extractor-paths/file-systems.png":::
15+
16+
*Each circle represents a file that may or may not have more file systems within it. The extractor repeatedly extracts each circle until there are no more circles (files) within it to be extracted.*
17+
18+
If the large, encompassing oval represents the firmware image, the three circles within the large oval may represent individual file systems within this firmware image. The circles may even represent executables with embedded file systems within them.
19+
20+
Because of the complex structure of firmware images – any given layer could be an executable or a file system with another embedded executable or file system – we need a comprehensive way to present the extraction results to accurately reflect a firmware image’s structure.
21+
22+
**How the Extractor Works**
23+
24+
The Firmware Analysis extractor identifies and decompresses data found within firmware images. There are multiple types of extractors, one for each type of file. For a full list of file formats that Firmware Analysis supports, check [Firmware analysis Frequently Asked Questions](firmware-analysis-faq.md).
25+
26+
For example, a `ZipArchive` extractor would extract a `ZipArchive` file. The extractor extracts the image as it sits on the disk in your system, and you will need to correlate the file path to the structure of files on your build environment. When you upload your firmware images to the Firmware Analysis service, the extractor recursively extracts the image until it cannot extract further. This means that the original firmware image is decompressed into individual files, and each individual file is sent again to the extractor to see if they can be further decompressed. This repeats until the extractor cannot decompress further.
27+
28+
Sometimes, there may be numerous files concatenated into one. Extractor will identify that there are numerous files in that one file, and use the appropriate extractor to extract each file, then put each file into its own respective directory. This means that if there were four files that were compiled with `GZip`, and they were concatenated into one file, extractor will identify that there are four `GZip` files at that level of extraction. Extractor will put the first `GZip` file into a directory named `GZipExtractor/1`, the second into a directory named `GZipExtractor/2`, and so on.
29+
30+
## Interpret File Paths Created by the Extractor
31+
32+
In the Firmware Analysis service, the SBOM view of the analysis results contains the file paths:
33+
34+
:::image type="content" source="media/extractor-paths/sbom-view.png" alt-text="Screenshot of SBOM view in the Firmware analysis results." lightbox="media/extractor-paths/sbom-view.png":::
35+
36+
Here is an example of a file path that might be seen in analysis results, and how to visualize the path in a file-system structure:
37+
38+
:::image type="content" source="media/extractor-paths/sample-path.png" alt-text="Screenshot of a sample file path by the extractor." lightbox="media/extractor-paths/sample-path.png":::
39+
40+
The following file-system structure is a visual representation of the SBOM file path:
41+
42+
:::image type="content" source="media/extractor-paths/sample-file-system-structure.png" alt-text="Screenshot of a sample file system structure." lightbox="media/extractor-paths/sample-file-system-structure.png":::
43+
44+
In this sample file path, a `ZipArchiveExtractor` extracted a `ZipArchive`, and it puts the contents into a directory named `ZipArchiveExtractor/1`. Again, the ‘1’ means that this was the first – and possibly, the only – `ZipArchive` file at this level of extraction. The extractor assigns a default name called `zip-root` to the `ZipArchive` file.
45+
46+
:::image type="content" source="media/extractor-paths/zip-root-in-file-system.png" alt-text="Screenshot of the zip-root in the file system." lightbox="media/extractor-paths/zip-root-in-file-system.png":::
47+
48+
> [!Note]
49+
> Usually, you can assume that a subdirectory with the suffix `-root` is created by Extractor and does not actually exist in your environment. It is just a subdirectory created by Extractor to hold the contents of that file type.
50+
>
51+
52+
Within `zip-root` is the `adhoc` file:
53+
54+
:::image type="content" source="media/extractor-paths/ziproot-adhoc-in-file-system.png" alt-text="Screenshot of the zip-root and adhoc files in the file system." lightbox="media/extractor-paths/ziproot-adhoc-in-file-system.png":::
55+
56+
Within the `adhoc` file is the `lede-17.01.4-arc770-generic-nsim-initramfs.elf` file:
57+
58+
:::image type="content" source="media/extractor-paths/adhoc-lede-in-file-system.png" alt-text="Screenshot of the adhoc and lede files in the file system." lightbox="media/extractor-paths/adhoc-lede-in-file-system.png":::
59+
60+
Since the `lede…` file ends with `.extracted`, this means that there is something within this `.elf` file that needs to be extracted further. The next extractor used was a `CPIOArchiveExtractor`, which means that there was a `CPIOArchive` file system embedded in the `.elf` file. The contents of the `CPIOArchive` file were placed in a `cpio-root` subdirectory:
61+
62+
:::image type="content" source="media/extractor-paths/cpio-root-in-file-system.png" alt-text="Screenshot of the cpio-root file in the file system." lightbox="media/extractor-paths/cpio-root-in-file-system.png":::
63+
64+
and within the `CPIOArchive` file, there was a `bin` file, and that `bin` file had a file named `busybox` within it:
65+
66+
:::image type="content" source="media/extractor-paths/cpio-bin-busybox-in-file-system.png" alt-text="Screenshot of the cpio-root, bin, and busybox files in the file system." lightbox="media/extractor-paths/cpio-bin-busybox-in-file-system.png":::
67+
68+
## Locate the Path in your Environment
69+
70+
Since the first extractor that was used was a `ZipArchiveExtractor`, this means that everything exists in a `Zip` file. Locate the `Zip` file, and within that, the full path on your environment would be `/adhoc/lede-17.01.4-arc770-generic-nsim-initramfs.elf.extracted/bin/busybox`. However, assume that you can only see into the first level of extraction – the `.elf` file. To see further, you would need your own extractor to extract beyond the first layer. This means that, tangibly, the file path to go to would be: `/adhoc/lede-17.01.4-arc770-generic-nsim-initramfs.elf`.
71+
72+
## Multiple Extractor Paths
73+
74+
In some cases, you may notice a `(+1)` or `(+2)` next to the file path:
75+
76+
:::image type="content" source="media/extractor-paths/multiple-paths.png" alt-text="Screenshot of an SBOM with multiple paths." lightbox="media/extractor-paths/multiple-paths.png":::
77+
78+
When you hover over the number, you’ll see a pop-up that looks like this:
79+
80+
:::image type="content" source="media/extractor-paths/pop-up-multiple-paths.png" alt-text="Screenshot of an SBOM's multiple paths." lightbox="media/extractor-paths/pop-up-multiple-paths.png":::
81+
82+
This means that the SBOM can be found at these two executable paths.
83+
88.8 KB
Loading
89.3 KB
Loading
88.6 KB
Loading
115 KB
Loading
69.2 KB
Loading
158 KB
Loading

0 commit comments

Comments
 (0)