Pre-GA reviews and fixes from PM and ENG

Author: mlottner

articles/asc-for-iot/concept-recommendations.md

@@ -32,11 +32,11 @@ Device recommendations provide insights and suggestions to improve device securi
 
 | Severity | Name                                                      | Data Source | Description                                                                                                                                                                                           |
 |----------|-----------------------------------------------------------|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| Medium   | Open Ports on device                                      | Agent       | A listening endpoint was found on the device                                                                                                                                                          |
+| Medium   | Open Ports on device                                      | Agent       | A listening endpoint was found on the device .                                                                                                                                                        |
 | Medium   | Permissive firewall policy found in one of the chains. | Agent       | Allowed firewall policy found (INPUT/OUTPUT). Firewall policy should deny all traffic by default, and define rules to allow necessary communication to/from the device.                               |
 | Medium   | Permissive firewall rule in the input chain was found     | Agent       | A rule in the firewall has been found that contains a permissive pattern for a wide range of IP addresses or ports.                                                                                    |
 | Medium   | Permissive firewall rule in the output chain was found    | Agent       | A rule in the firewall has been found that contains a permissive pattern for a wide range of IP addresses or ports.                                                                                   |
-| Medium   | Operation system baseline validation has failed           | Agent       | Device doesn't comply with [CIS Linux benchmarks](https://www.cisecurity.org/cis-benchmarks/)                                                                                                         |
+| Medium   | Operation system baseline validation has failed           | Agent       | Device doesn't comply with [CIS Linux benchmarks](https://www.cisecurity.org/cis-benchmarks/).                                                                                                        |
 
 ### Operational recommendations for IoT devices
 
@@ -46,7 +46,7 @@ Operational recommendations provide insights and suggestions to improve security
 |----------|-----------------------------------------|-------------|-----------------------------------------------------------------------------------|
 | Low      | Agent sends unutilized messages          | Agent       | 10% or more of security messages were smaller than 4kb during the last 24 hours.  |
 | Low      | Security twin configuration not optimal | Agent       | Security twin configuration is not optimal.                                        |
-| Low      | Security twin configuration conflict    | Agent       | Conflicts were identified in the security twin configuration.                           |
+| Low      | Security twin configuration conflict    | Agent       | Conflicts were identified in the security twin configuration. |                          |
 
 
 ## Recommendations for IoT Hub

articles/asc-for-iot/concept-security-agent-authentication-methods.md

@@ -26,15 +26,15 @@ This article explains the different authentication methods you can use with the
 For each device onboarded to Azure Security Center for IoT in the IoT Hub, a security module is required. To authenticate the device, Azure Security Center for IoT can use one of two methods. Choose the method that works best for your existing IoT solution. 
 
 > [!div class="checklist"]
-> * Security Module option
+> * SecurityModule option
 > * Device option
 
 ## Authentication methods
 
 The two methods for the AzureIoTSecurity agent to perform authentication:
 
- - **Module** authentication mode<br>
-   The Module is authenticated independently of the device twin.
+ - **SecurityModule** authentication mode<br>
+   The agent is authenticated using the security module identity independently of the device identity.
    Use this authentication type if you would like the security agent to use a dedicated authentication method through security module (symmetric key only).
 
  - **Device** authentication mode<br>
@@ -46,7 +46,7 @@ See [Security agent installation parameters](#security-agent-installation-parame
 
 ## Authentication methods known limitations
 
-- **Module** authentication mode only supports symmetric key authentication.
+- **SecurityModule** authentication mode only supports symmetric key authentication.
 - CA-Signed certificate is not supported by **Device** authentication mode.  
 
 ## Security agent installation parameters
@@ -55,19 +55,18 @@ When [deploying a security agent](how-to-deploy-agent.md), authentication detail
 These arguments are documented in the following table.
 
 
-|Parameter|Description|Options|
-|---------|---------------|---------------|
-|**identity**|Authentication mode| **Module** or **Device**|
-|**type**|Authentication type|**SymmetricKey** or **SelfSignedCertificate**|
-|**filePath**|Absolute full path for the file containing the certificate or the symmetric key| |
-|**gatewayHostname**|FQDN of the IoT Hub|Example: ContosoIotHub.azure-devices.net|
-|**deviceId**|Device ID|Example: MyDevice1|
-|**certificateLocationKind**|Certificate storage location|**LocalFile** or **Store**|
+|Linux Parameter Name | Windows Parameter Name | Shorthand Parameter |Description|Options|
+|---------------------|---------------|---------|---------------|---------------|
+|authentication-identity|AuthenticationIdentity|aui|Authentication identity| **SecurityModule** or **Device**|
+|authentication-method|AuthenticationMethod|aum|Authentication method|**SymmetricKey** or **SelfSignedCertificate**|
+|file-path|FilePath|f|Absolute full path for the file containing the certificate or the symmetric key| |
+|host-name|HostName|hn|FQDN of the IoT Hub|Example: ContosoIotHub.azure-devices.net|
+|device-id|DeviceId|di|Device ID|Example: MyDevice1|
+|certificate-location-kind|CertificateLocationKind|cl|Certificate storage location|**LocalFile** or **Store**|
+|
 
 
-When using the install security agent script, the following configuration is performed automatically.
-
-To edit the security agent authentication manually, edit the config file. 
+When using the install security agent script, the following configuration is performed automatically. To edit the security agent authentication manually, edit the config file. 
 
 ## Change authentication method after deployment
 
@@ -76,7 +75,7 @@ When deploying a security agent with an installation script, a configuration fil
 To change authentication methods after deployment, manual editing of the configuration file is required.
 
 
-### C# based security agent
+### C#-based security agent
 
 Edit _Authentication.config_ with the following parameters:
 
@@ -91,7 +90,7 @@ Edit _Authentication.config_ with the following parameters:
 </Authentication>
 ```
 
-### C based security agent
+### C-based security agent
 
 Edit _LocalConfiguration.json_ with the following parameters:
 

articles/asc-for-iot/getting-started.md

@@ -29,13 +29,13 @@ Choose the service scenario that best meets your IoT device and environment requ
 ### Built-in deployment
 Using the seamless, built-in deployment option, Azure Security Center for IoT can be quickly integrated into your IoT Hub and provide security analysis of the IoT hub configuration, device identity and management, and hub-device communication patterns.
 
-* Start a [Built-in deployment](iot-hub-integration.md) featuring IoT Hub monitoring and recommendations. 
+Start a [Built-in deployment](iot-hub-integration.md) featuring IoT Hub monitoring and recommendations. 
     <br>
 
 ### Enhanced deployment
 For enhanced security capabilities, deploying Azure Security Center for IoT agents in addition to enabling IoT Hub security provides agent-based event collection, analysis and threat detection of key security data from your IoT devices as well as comprehensive security posture management capabilities.
 
-* Start an [Enhanced deployment](security-agents.md) featuring an agent-based comprehensive threat protection and security posture management solution.
+Start an [Enhanced deployment](security-agents.md) featuring an agent-based comprehensive threat protection and security posture management solution.
 
 
 ## Next steps

articles/asc-for-iot/how-to-deploy-agent.md

@@ -24,7 +24,7 @@ ms.author: mlottner
 Azure Security Center for IoT provides reference architectures for security agents that monitor and collect data from IoT devices.
 To learn more, see [Security agent reference architecture](security-agent-architecture.md).
 
-Agents are developed as open source projects, and are available in two flavors: <br> [C](https://aka.ms/iot-security-github-c), and [C#](https://aka.ms/iot-security-github-cs).
+Agents are developed as open-source projects, and are available in two flavors: <br> [C](https://aka.ms/iot-security-github-c), and [C#](https://aka.ms/iot-security-github-cs).
 
 In this article, you learn how to: 
 > [!div class="checklist"]
@@ -40,18 +40,27 @@ The C-based security agent has a lower memory footprint, and is the ideal choice
 
 |     | C-based security agent | C#-based security agent |
 | --- | ----------- | --------- |
-| Open source | Available under [MIT license](https://en.wikipedia.org/wiki/MIT_License) in [Github](https://aka.ms/iot-security-github-cs) | Available under [MIT license](https://en.wikipedia.org/wiki/MIT_License) in [Github](https://aka.ms/iot-security-github-c) |
+| Open-source | Available under [MIT license](https://en.wikipedia.org/wiki/MIT_License) in [GitHub](https://aka.ms/iot-security-github-cs) | Available under [MIT license](https://en.wikipedia.org/wiki/MIT_License) in [GitHub](https://aka.ms/iot-security-github-c) |
 | Development language    | C | C# |
 | Supported Windows platforms? | No | Yes |
 | Windows prerequisites | --- | [WMI](https://docs.microsoft.com/windows/desktop/wmisdk/) |
 | Supported Linux platforms? | Yes, x64 and x86 | Yes, x64 only |
 | Linux prerequisites | libunwind8, libcurl3, uuid-runtime, auditd, audispd-plugins | libunwind8, libcurl3, uuid-runtime, auditd, audispd-plugins, sudo, netstat, iptables |
-| Disk footprint | 10.5MB | 90MB |
-| Memory footprint (on average) | 5.5MB | 33MB |
+| Disk footprint | 10.5 MB | 90 MB |
+| Memory footprint (on average) | 5.5 MB | 33 MB |
 | [Authentication](concept-security-agent-authentication-methods.md) to IoT Hub | Yes | Yes |
 | Security data [collection](how-to-agent-configuration.md#supported-security-events) | Yes | Yes |
 | Event aggregation | Yes | Yes |
 | Remote configuration through [security module twin](concept-security-module.md) | Yes | Yes |
+|
+
+## Security agent installation guidelines
+
+For **Windows**:
+The Install SecurityAgent.ps1 script must be executed from an Administrator PowerShell window. 
+
+For **Linux**:
+The InstallSecurityAgent.sh must be run as superuser. We recommend prefixing the installation command with “sudo”.
 
 
 ## Choose an agent flavor 

articles/asc-for-iot/how-to-deploy-edge.md

@@ -132,7 +132,8 @@ There are three steps to create an IoT Edge deployment for Azure Security Center
 
 #### Step 2: Specify Routes 
 
-1. In the **Specify Routes** tab, make sure you have a route (explicit or implicit) that will forward messages from the **azureiotsecurity** module to **$upstream**, then click Next.
+1. In the **Specify Routes** tab, make sure you have a route (explicit or implicit) that will forward messages from the **azureiotsecurity** module to **$upstream**. 
+1. Click **Next**.
 
     ~~~Default implicit route
     "route": "FROM /messages/* INTO $upstream 
@@ -144,7 +145,7 @@ There are three steps to create an IoT Edge deployment for Azure Security Center
 
 #### Step 3: Review Deployment
 
-1. In the **Review Deployment** tab, review your deployment information, then select **Submit** to complete the deployment.
+- In the **Review Deployment** tab, review your deployment information, then select **Submit** to complete the deployment.
 
 ## Diagnostic steps
 

articles/asc-for-iot/how-to-deploy-linux-c.md

@@ -39,14 +39,14 @@ For other platforms and agent flavors, see [Choose the right security agent](how
 
 ## Installation 
 
-To install and deploy the security agent, do the following:
+To install and deploy the security agent, use the following workflow:
 
 
-1. Download the most recent version to your machine from [Github](https://aka.ms/iot-security-github-c).
+1. Download the most recent version to your machine from [GitHub](https://aka.ms/iot-security-github-c).
 
 1. Extract the contents of the package and navigate to the _/Install_ folder.
 
-1. Add running permissions to the **InstallSecurityAgent script** by running the following:
+1. Add running permissions to the **InstallSecurityAgent script** by running the following command:
 
    ```
    chmod +x InstallSecurityAgent.sh
@@ -60,11 +60,11 @@ To install and deploy the security agent, do the following:
 
    See [How to configure authentication](concept-security-agent-authentication-methods.md) for more information about authentication parameters.
 
-This script does the following:
+This script performs the following function:
 
 1. Installs prerequisites.
 
-2. Adds a service user (with interactive login disabled).
+2. Adds a service user (with interactive sign in disabled).
 
 3. Installs the agent as a **Daemon** - assumes the device uses **systemd** for service management.
 

articles/asc-for-iot/how-to-deploy-linux-cs.md

@@ -40,9 +40,9 @@ For other platforms and agent flavors, see [Choose the right security agent](how
 
 ## Installation 
 
-To deploy the security agent, do the following:
+To deploy the security agent, use the following steps:
 
-1. Download the most recent version to your machine from [Github](https://aka.ms/iot-security-github-cs).
+1. Download the most recent version to your machine from [GitHub](https://aka.ms/iot-security-github-cs).
 
 1. Extract the contents of the package and navigate to the _/Install_ folder.
 
@@ -54,17 +54,17 @@ To deploy the security agent, do the following:
    ./InstallSecurityAgent.sh -i -aui <authentication identity>  -aum <authentication method> -f <file path> -hn <host name>  -di <device id> -cl <certificate location kind>
    ```
 
-   See [How to configure authentication](concept-security-agent-authentication-methods.md) for more information about authentication parameters.
+   for more information about authentication parameters, see [How to configure authentication](concept-security-agent-authentication-methods.md).
 
-This script does the following:
+This script performs the following actions:
 
 - Installs prerequisites.
 
-- Adds a service user (with interactive login disabled).
+- Adds a service user (with interactive sign in disabled).
 
-- Installs the agent as a **Daemon** - this assumes the device uses **systemd** for service management.
+- Installs the agent as a **Daemon** - assumes the device uses **systemd** for classic deployment model.
 
-- Configures **sudoers** to allow the agent to perform certain tasks as root.
+- Configures **sudoers** to allow the agent to do certain tasks as root.
 
 - Configures the agent with the provided authentication parameters.
 

articles/asc-for-iot/how-to-deploy-windows-cs.md

@@ -32,25 +32,27 @@ In this guide, you learn how to:
 
 ## Prerequisites
 
-For other platforms and agent flavours, see [Choose the right security agent](how-to-deploy-agent.md).
+For other platforms and agent flavors, see [Choose the right security agent](how-to-deploy-agent.md).
 
 1. Local admin rights on the machine you wish to install on. 
 
 1. [Create a security module](quickstart-create-security-twin.md) for the device.
 
 ## Installation 
 
-To install the security agent, do the following:
+To install the security agent, use the following workflow:
 
-1. To install the Azure Security Center for IoT Windows C# agent on the device, download the most recent version to your machine from the Azure Security Center for IoT [GitHub repository](https://github.com/Azure/Azure-IoT-Security-Agent-CS).
+1. Install the Azure Security Center for IoT Windows C# agent on the device. Download the most recent version to your machine from the Azure Security Center for IoT [GitHub repository](https://github.com/Azure/Azure-IoT-Security-Agent-CS).
 
-2. Extract the contents of the package, and navigate to the /Install folder.
+1. Extract the contents of the package, and navigate to the /Install folder.
 
-3. Open Windows PowerShell as Administrator. 
-    1. Add running permissions to the InstallSecurityAgent script by running
-    ```Unblock-File .\InstallSecurityAgent.ps1```
+1. Open Windows PowerShell as Administrator. 
+1. Add running permissions to the InstallSecurityAgent script by running:<br>
+    ```
+    Unblock-File .\InstallSecurityAgent.ps1
+    ```
     
-        and run:
+    then run:
 
     ```
 	.\InstallSecurityAgent.ps1 -Install -aui <authentication identity> -aum <authentication method> -f <file path> -hn <host name> -di <device id> -cl <certificate location kind>
@@ -62,13 +64,13 @@ To install the security agent, do the following:
 	.\InstallSecurityAgent.ps1 -Install -aui Device -aum SymmetricKey -f c:\Temp\Key.txt -hn MyIotHub.azure-devices.net -di Mydevice1 -cl store
 	```
 	
-	See [How to configure authentication](concept-security-agent-authentication-methods.md) for more information about authentication parameters.
+	For more information about authentication parameters, see [How to configure authentication](concept-security-agent-authentication-methods.md).
 
-This script does the following:
+This script does the following actions:
 
 - Installs prerequisites.
 
-- Adds a service user (with interactive login disabled).
+- Adds a service user (with interactive sign in disabled).
 
 - Installs the agent as a **System Service**.