IDENTITY-BASED MICROSEGMENTATION DOCUMENTATION

Windows hosts

About Windows host installs

To deploy the enforcer to a Windows host, use one of the following procedures.

  • Quick install: the fastest way to install an enforcer on a Windows host.

  • Advanced cloud install: the enforcer uses short-lived tokens from AWS, GCP, or Azure to authenticate to the Microsegmentation Console.

  • Advanced on-premise install: you pass a restricted token to the enforcer. The enforcer exchanges the token for an app credential. This method ensures that the app credential never travels the wire.

Quick install

  1. Make sure you meet the following prerequisites.

    Entity Requirement
    Target host(s) Meets the system requirements
    Set up to synchronize time with authoritative sources
    curl installed
    jq installed
    Local host apoctl installed
    Privileges namespace.administrator privileges in the Microsegmentation namespace of the target host
    ■ Administrator access to the target host
  2. Copy the app credential from your local host to the target host. You can accomplish this in various ways. We provide some code below for your convenience. To use this, you must replace the example IP address with the actual public IP of the target host, provide the user name and password for the target host at the prompt, and ensure that the target host accepts Windows Remote Management (WinRM) connections over HTTP and HTTPS.

    $ip = '3.137.207.168'
    Set-Item -Path WSMan:\localhost\Client\TrustedHosts -Value $ip
    $creds = Get-Credentials
    $session = New-PSSession –ComputerName $ip -Credentials $creds
    Copy-Item –Path ~/.apoctl/default.creds –Destination 'C:\' –ToSession $session
    $session | Remove-PSSession
    
  3. Access the target host, such as via Microsoft Remote Desktop.

  4. Download the apoctl MSI to the target host and execute it in quiet mode.

    curl https://download.aporeto.com/apoctl/windows/apoctl.msi -o apoctl.msi; `
    if ($?) {. .\apoctl.msi /quiet}
    if ($?) {$env:PATH+="C:\Program Files\Apoctl;"}
    
  5. Set a TARGET_NS environment variable containing the Microsegmentation namespace of this enforcer. It should be a great grandchild namespace.

    $env:TARGET_NS="/acme/team-a/dev/vm1"
    
  6. Set a MICROSEG_API environment variable containing the URL of your Microsegmentation Console API. The command below uses jq to extract this value from your app credential.

    $env:MICROSEG_API = (apoctl auth verify --creds C:\default.creds | jq -r '.iss')
    
  7. Use the following command to install the enforcer.

    apoctl protect windows --creds C:\default.creds `
                           --auth-mode appcred `
                           --namespace $($env:TARGET_NS) `
                           --raw-flags '--log-level=debug --log-format=human --log-to-console=true' `
                           --repo https://repo.aporeto.com/windows/enforcer.msi
    

    TIP

    Refer to Enforcer configuration options if you wish to modify the enforcer’s default settings. You can find more information about the protect command in the apoctl reference page.

  8. Use the following command to check the status of the enforcer.

    apoctl api list enforcers --creds C:\default.creds `
                              --namespace $($env:TARGET_NS) `
                              -o table `
                              -c ID `
                              -c name `
                              -c namespace `
                              -c operationalStatus
    
  9. apoctl should return information about the enforcer you just deployed, including an operationalStatus of Connected.

                 ID            |                              name                              |      namespace       | operationalStatus
    ---------------------------+----------------------------------------------------------------+----------------------+--------------------
      5f80da12f0fe1707f390e9ff | ami-0ca69a9d06da3835d:i-06a4868a981a30f15:2020-10-09T18:50:21Z | /acme/team-a/dev/vm1 | Connected
    
  10. Open the In the Microsegmentation section of the Prisma Cloud web interface, navigate to the enforcer’s namespace, expand Manage, and select Enforcers. You should find your enforcer listed with a status of connected. Click the enforcer and review its metadata.

  11. Select Platform in the side navigation menu. You should see your host as a processing unit, with dashed green lines to any-udp and any-tcp external networks. Your host is in discovery mode.

  12. Remove your administrative credentials from the target host and uninstall apoctl.

    Remove-Item 'C:\default.creds' 
    Remove-Item '.apoctl' -Recurse
    msiexec /x apoctl.msi /quiet
    Remove-Item apoctl.msi
    
  13. Refer to Securing host communications to learn how to allow the desired traffic and disable discovery mode.

Advanced cloud install

  1. Ensure that you meet the following prerequisites.

    Entity Requirement
    Target host Meets the system requirements
    Set up to synchronize time with authoritative sources
    apoctl host apoctl installed
    Privileges namespace.administrator privileges in the target Microsegmentation namespace
    ■ Administrator access to the target instance
    Cloud credentials AWS: an IAM role attached to the target host with read-only access to tags (ec2:DescribeTags)
    GCP: GCP service account attached to the target host
    Azure: target host assigned a managed identity
  2. On your apoctl host, construct a Microsegmentation tag that identifies your cloud account, project, tenant, or organization. The tag must begin with @auth: followed by a key-value pair. Refer to the table below for some common examples.

    Cloud provider Value Microsegmentation tag syntax Microsegmentation tag example
    AWS AWS account ID* @auth:account=<AWS_ACCOUNT_ID> @auth:account=942613894219
    GCP GCP project ID @auth:projectid=<GCP_PROJECT_ID> @auth:projectid=acme-dev
    Azure Microsoft tenant ID @auth:tenantid=<TENANT_ID> @auth:tenantid=cd629cb5-2826-4126-82fd-3f2df5f5bc7
    GCP and Azure Name of organization @auth:organization=<ORGANIZATION> @auth:organization=acme

    * You can find your AWS account ID under My security credentials in the AWS Management Console.
    To learn how to find your tenant ID, refer to the Microsoft documentation.

  3. Set a CLOUD_ID_TAG environment variable containing the Microsegmentation tag you’ve constructed to identify authorized enforcers. If the target virtual machine is hosted on AWS, also set an AWS_IAM_ROLE environment variable containing the name of the IAM role attached to the instance prepended with @auth:rolename=. For examples, see below.

    $env:CLOUD_ID_TAG="@auth:account=942613894219"
    $env:AWS_IAM_ROLE="@auth:rolename=aporeto"
    
    $env:CLOUD_ID_TAG="@auth:projectid=acme-dev"
    
    $env:CLOUD_ID_TAG="@auth:tenantid=cd629cb5-2826-4126-82fd-3f2df5f5bc7"
    

  4. Set a TARGET_NS environment variable containing the Microsegmentation namespace that this enforcer should register in. It should be a great grandchild namespace.

    $env:TARGET_NS="/acme/team-a/dev/vm1"
    
  5. (Optional) You can use cloud metadata to map the enforcer into the target namespace. Set an ENFORCER_ID_TAG environment variable with the Microsegmentation tag that contains the identifying cloud metadata. We provide example cloud metadata below and the command to create the namespace mapping.

    $env:ENFORCER_ID_TAG="@cloud:aws:type=ec2" 
    Set-Content -Path ns-map.yml -Value @"
    APIVersion: 0
    label: ec2-namespace-map
    data:
     namespacemappingpolicies:
       - mappedNamespace: $($env:TARGET_NS)
         metadata: []
         name: Map $($env:ENFORCER_ID_TAG) instance to $($env:TARGET_NS) namespace
         subject:
           - - "`$identity=enforcer"
             - "$($env:ENFORCER_ID_TAG)"
    "@ ; if ($?) 
    { apoctl api import -f ns-map.yml }
    
    $env:ENFORCER_ID_TAG="@cloud:gcp:zone=us-central1-a" 
    Set-Content -Path ns-map.yml -Value @"
    APIVersion: 0
    label: gcp-namespace-map
    data:
     namespacemappingpolicies:
       - mappedNamespace: $($env:TARGET_NS)
         metadata: []
         name: Map $($env:ENFORCER_ID_TAG) instance to $($env:TARGET_NS) namespace
         subject:
           - - "`$identity=enforcer"
             - "$($env:ENFORCER_ID_TAG)"
    "@ ; if ($?) 
    { apoctl api import -f ns-map.yml }
    
    $env:ENFORCER_ID_TAG="@cloud:azure:location=centralus" 
    Set-Content -Path ns-map.yml -Value @"
    APIVersion: 0
    label: azure-namespace-map
    data:
     namespacemappingpolicies:
       - mappedNamespace: $($env:TARGET_NS)
         metadata: []
         name: Map $($env:ENFORCER_ID_TAG) instance to $($env:TARGET_NS) namespace
         subject:
           - - "`$identity=enforcer"
             - "$($env:ENFORCER_ID_TAG)"
    "@ ; if ($?) 
    { apoctl api import -f ns-map.yml }
    

  6. Use one of the following commands to create an API authorization that allows the enforcer to access the Microsegmentation Console. Select the tab that corresponds to the cloud provider of the target host and whether or not you are using the optional mapping.

    $env:CURRENT_NS = ( apoctl auth verify | jq -r '.data.organization' ) | Out-String
    Set-Content -Path enf-api-auth.yml -Value @"
    APIVersion: 0
    label: ec2-enforcerd-auth
    data:
     apiauthorizationpolicies:
       - authorizedIdentities:
           - '@auth:role=enforcer'
         authorizedNamespace: $($env:CURRENT_NS)
         authorizedSubnets: []
         name: Authorize EC2 enforcer to access Microsegmentation Console
         propagate: true
         subject:
           - - "@auth:realm=awssecuritytoken"
             - "$($env:AWS_IAM_ROLE)"
             - "$($env:CLOUD_ID_TAG)"
    "@ ; if ($?) 
    { apoctl api import -f enf-api-auth.yml }
    
    Set-Content -Path enf-api-auth.yml -Value @"
    APIVersion: 0
    label: ec2-enforcerd-auth
    data:
     apiauthorizationpolicies:
       - authorizedIdentities:
           - '@auth:role=enforcer'
         authorizedNamespace: $($env:TARGET_NS)
         authorizedSubnets: []
         name: Authorize EC2 enforcer to access Microsegmentation Console
         propagate: true
         subject:
           - - "@auth:realm=awssecuritytoken"
             - "$($env:AWS_IAM_ROLE)"
             - "$($env:CLOUD_ID_TAG)"
    "@ ; if ($?) 
    { apoctl api import -f enf-api-auth.yml }
    
    $env:CURRENT_NS = ( apoctl auth verify | jq -r '.data.organization' ) | Out-String
    Set-Content -Path enf-api-auth.yml -Value @"
    APIVersion: 0
    label: gcp-enforcerd-auth
    data:
     apiauthorizationpolicies:
       - authorizedIdentities:
           - '@auth:role=enforcer'
         authorizedNamespace: $($env:CURRENT_NS)
         authorizedSubnets: []
         name: Authorize GCP enforcer to access Microsegmentation Console
         propagate: true
         subject:
           - - "@auth:realm=gcpidentitytoken"
             - "$($env:CLOUD_ID_TAG)"
    "@ ; if ($?) 
    { apoctl api import -f enf-api-auth.yml }
    
    Set-Content -Path enf-api-auth.yml -Value @"
    APIVersion: 0
    label: gcp-enforcerd-auth
    data:
     apiauthorizationpolicies:
       - authorizedIdentities:
           - '@auth:role=enforcer'
         authorizedNamespace: $($env:TARGET_NS)
         authorizedSubnets: []
         name: Authorize GCP enforcer to access Microsegmentation Console
         propagate: true
         subject:
           - - "@auth:realm=gcpidentitytoken"
             - "$($env:CLOUD_ID_TAG)"
    "@ ; if ($?) 
    { apoctl api import -f enf-api-auth.yml }
    
    $env:CURRENT_NS = ( apoctl auth verify | jq -r '.data.organization' ) | Out-String
    Set-Content -Path enf-api-auth.yml -Value @"
    APIVersion: 0
    label: azure-enforcerd-auth
    data:
     apiauthorizationpolicies:
       - authorizedIdentities:
           - '@auth:role=enforcer'
         authorizedNamespace: $($env:CURRENT_NS)
         authorizedSubnets: []
         name: Authorize Azure enforcer to access Microsegmentation Console
         propagate: true
         subject:
           - - "@auth:realm=azureidentitytoken"
             - "$($env:CLOUD_ID_TAG)"
    "@ ; if ($?) 
    { apoctl api import -f enf-api-auth.yml }
    
    Set-Content -Path enf-api-auth.yml -Value @"
    APIVersion: 0
    label: azure-enforcerd-auth
    data:
     apiauthorizationpolicies:
       - authorizedIdentities:
           - '@auth:role=enforcer'
         authorizedNamespace: $($env:TARGET_NS)
         authorizedSubnets: []
         name: Authorize Azure enforcer to access Microsegmentation Console
         propagate: true
         subject:
           - - "@auth:realm=azureidentitytoken"
             - "$($env:CLOUD_ID_TAG)"
    "@ ; if ($?) 
    { apoctl api import -f enf-api-auth.yml }
    

  7. Use the following command to obtain the URL of your Microsegmentation Console API.

    $env:MICROSEG_API
    
  8. Use one of the following commands to get the enforcer’s namespace. If you are using a namespace mapping, the correct value is your current namespace. If you are not using a namespace mapping, the correct value is the TARGET_NS

    $env:TARGET_NS
    
    $env:CURRENT_NS
    

  9. Access the target host, such as via Microsoft Remote Desktop.

  10. Paste the URL of your Microsegmentation Console API into a MICROSEG_API and the enforcer’s namespace into an ENFORCER_NS environment variables, as retrieved by the previous commands.

    $env:ENFORCER_NS="<paste-value>" `
    $env:MICROSEG_API="<paste-value>"
    
  11. Download the enforcer installer package using curl.

    curl https://download.aporeto.com/enforcerd/windows/enforcer.msi -o enforcer.msi 
    
  12. Use the following command to install and start the enforcer.

    msiexec /i enforcer.msi ENFORCERD_API=$($env:MICROSEG_API) `
    ENFORCERD_NAMESPACE=$($env:ENFORCER_NS) `
    ENFORCERD_OPTS="--log-level=debug" ATTESTMETHOD=0 /qn ; if ($?)
    {Start-Sleep -s 10} ; if ($?)
    {& sc.exe qc "Aporeto Enforcer"} ; if ($?)
    {& sc.exe start "Aporeto Enforcer"} ; if ($?) 
    {Start-Sleep -s 10} ; if ($?)
    {& sc.exe query "Aporeto Enforcer"}
    

    TIP

    You can find the enforcer’s logs under C:\ProgramData\enforcerd\log. The directory may be hidden by default. If so, type %programdata% in Windows Search. Refer to Enforcer configuration options to learn about modifying the enforcer’s default settings.

  13. Use the following command to check the status of the enforcer.

    apoctl api list enforcers --namespace $($env:TARGET_NS) `
                              -o table `
                              -c ID `
                              -c name `
                              -c namespace `
                              -c operationalStatus
    
  14. apoctl should return information about the enforcer you just deployed, including an operationalStatus of Connected.

                 ID            |                              name                              |      namespace       | operationalStatus
    ---------------------------+----------------------------------------------------------------+----------------------+--------------------
      5f80da12f0fe1707f390e9ff | ami-0ca69a9d06da3835d:i-06a4868a981a30f15:2020-10-09T18:50:21Z | /acme/team-a/dev/vm1 | Connected
    
  15. Open the In the Microsegmentation section of the Prisma Cloud web interface, navigate to the enforcer’s namespace, expand Manage, and select Enforcers. You should find your enforcer listed with a status of connected. Click the enforcer and review its metadata.

  16. Select Platform in the side navigation menu. You should see your host as a processing unit, with dashed green lines to any-udp and any-tcp external networks. Your host is in discovery mode. Refer to Securing host communications to learn how to allow the desired traffic and disable discovery mode.

Advanced on-premise install

  1. Ensure you meet the following prerequisites.

    Entity Requirement
    Target host(s) Meets the system requirements
    Set up to synchronize time with authoritative sources
    curl installed
    apoctl host apoctl installed
    Privileges namespace.administrator privileges in the Microsegmentation namespace of the target host
    ■ Administrator access to the target host
  2. On the apoctl host, use the following command to create an app credential with the enforcer role.

    apoctl appcred create enforcerd --role @auth:role=enforcer > enforcerd.creds
    
  3. Use the app credential to generate an enforcer registration token with the desired restrictions. At a minimum, we recommend restricting the length of its validity and role. You can also require the enforcer to register in a specified namespace or make its request from a specific subnet.

    apoctl auth appcred --path enforcerd.creds \
                        --restrict-role @auth:role=enforcer \
                        --validity <golang-duration> \
                        [--restrict-namespace <namespace>] \
                        [--restrict-network <cidr>]
    
    apoctl auth appcred --path enforcerd.creds \
                        --restrict-namespace /acme/team-a/dev \
                        --restrict-role @auth:role=enforcer \
                        --restrict-network 10.0.0.0/8 \
                        --validity 10m
    
    apoctl auth appcred --path enforcerd.creds \
                        --restrict-role @auth:role=enforcer --validity 1h
    

  4. This should return a base64-encoded token. Copy the value.

  5. Access the target host, such as via a remote desktop client. Set an environment variable called TOKEN containing the value copied in the previous step.

    $env:TOKEN="<paste-token-value>"
    
  6. Set a TARGET_NS environment variable containing the Microsegmentation namespace that this enforcer should register in. It should be a great grandchild namespace.

    $env:TARGET_NS="/acme/team-a/dev/vm1"
    
  7. Set a MICROSEG_API environment variable containing the URL of your Microsegmentation Console API.

    $env:MICROSEG_API="https://api.console.aporeto.com:4443"
    
  8. Use curl to download the enforcer installer package.

    curl https://download.aporeto.com/enforcerd/windows/enforcer.msi -o enforcer.msi 
    
  9. You can configure the enforcer to store its app credential only in memory and not on disk. While more secure, this option requires someone to manually reprovision enforcer with a token following a reboot of the host. You can also configure the enforcer to store its app credential on disk, ensuring that it can reconnect to the Microsegmentation Console after a reboot without manual intervention.

    msiexec /i enforcer.msi ENFORCERD_API=$($env:MICROSEG_API) `
    ENFORCERD_NAMESPACE=$($env:TARGET_NS) `
    ENFORCERD_OPTS="--log-level=debug" `
    ENFORCERD_TOKEN=$($env:TOKEN) ATTESTMETHOD=2 /qn ; if ($?)
    {Start-Sleep -s 10} ; if ($?)
    {$values = Get-ItemPropertyValue -Path "HKLM:\SYSTEM\CurrentControlSet\Services\Aporeto Enforcer\" -Name "Environment" 
    $values += "ENFORCERD_PERSIST_CREDENTIALS=true"
    Set-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Services\Aporeto Enforcer\" -Name "Environment" -Type "MultiString" -Value $values} ; if ($?)
    {& sc.exe qc "Aporeto Enforcer"} ; if ($?)
    {& sc.exe start "Aporeto Enforcer"} ; if ($?) 
    {Start-Sleep -s 10} ; if ($?)
    {& sc.exe query "Aporeto Enforcer"}
    
    msiexec /i enforcer.msi ENFORCERD_API=$($env:MICROSEG_API) `
    ENFORCERD_NAMESPACE=$($env:TARGET_NS) `
    ENFORCERD_TOKEN=$($env:TOKEN) ATTESTMETHOD=2 /qn ; if ($?)
    {Start-Sleep -s 10} ; if ($?)
    {& sc.exe qc "Aporeto Enforcer"} ; if ($?)
    {& sc.exe start "Aporeto Enforcer"} ; if ($?) 
    {Start-Sleep -s 10} ; if ($?)
    {& sc.exe query "Aporeto Enforcer"}
    

    TIP

    You can find the enforcer’s logs under C:\ProgramData\enforcerd\log. The directory may be hidden by default, if so, type %programdata% in Windows Search. Refer to Enforcer configuration options to learn about modifying the enforcer’s default settings.

  10. Use the following command to check the status of the enforcer.

    apoctl api list enforcers --namespace $($env:TARGET_NS) `
                              -o table `
                              -c ID `
                              -c name `
                              -c namespace `
                              -c operationalStatus
    
  11. apoctl should return information about the enforcer you just deployed, including an operationalStatus of Connected.

                 ID            |                              name                              |      namespace       | operationalStatus
    ---------------------------+----------------------------------------------------------------+----------------------+--------------------
      5f80da12f0fe1707f390e9ff | ami-0ca69a9d06da3835d:i-06a4868a981a30f15:2020-10-09T18:50:21Z | /acme/team-a/dev/vm1 | Connected
    
  12. Open the In the Microsegmentation section of the Prisma Cloud web interface, navigate to the enforcer’s namespace, expand Manage, and select Enforcers. You should find your enforcer listed with a status of connected. Click the enforcer and review its metadata.

  13. Select Platform in the side navigation menu. You should see your host as a processing unit, with dashed green lines to any-udp and any-tcp external networks. Your host is in discovery mode. Refer to Securing host communications to learn how to allow the desired traffic and disable discovery mode.

Enforcer configuration options

The enforcer exposes the following configuration options at startup. To modify the configuration of a running enforcer, you must restart it.

You can modify the default configuration in two ways:

  • You can pass the flags with apoctl protect as the value of --raw-flags. Example: apoctl protect linux --raw-flags "--log-level=debug --log-format=human --log-to-console=true"

  • You can also pass the flags as the value of ENFORCERD_OPTS as arguments to the MSI package. Example: apoctl protect linux --raw-flags "--log-level=debug --log-format=human --log-to-console=true"

  • If you’re not using apoctl protect, you can pass some of them as arguments to the MSI package.

enforcer flag MSI arguments Description
--activate-control-plane-pus Pass this flag if you wish to recognize the Microsegmentation Console as a processing unit, allowing its communications to be monitored and controlled. By default, the enforcer ignores them.
--api ENFORCERD_API The URL of the Microsegmentation Console API.
--api-cacert Path to CA certificate.
--api-skip-verify Disables check on certificate signature as trusted.
--appcreds ENFORCERD_APPCREDS Path to application credentials.
--application-proxy-port Start of the port range for ports used by the enforcer application proxy. Defaults to 20992. You may adjust this if you experience conflicts.
--cloud-probe-timeout The enforcer can determine if it is running in a cloud environment, such as AWS, GCP, or Azure. This is the maximum amount of time to wait for these internal probes to complete. Defaults to two seconds: 2s
--disable-dns-proxy Pass this flag to disable the enforcer DNS proxy, which allows policies to be written based on FQDN, in cases where an exact IP address may be unpredictable.
--dns-server-address DNS server address or CIDR that is observed by the enforcer DNS proxy. Defaults to 0.0.0.0/0.
--enable-ebpf (Beta) Pass this flag to gain performance improvements by using extended Berkeley Packet Filter (eBPF) on systems that support it.
--enable-ipv6 (Beta) The enforcer ignores IPv6 communications by default. If you have IPv6 enabled and wish to monitor and control these connections, pass this flag.
--log-level Quantity of logs that the enforcer should generate. Defaults to info. Alternatively, you can set it to debug, trace, or warn.
--log-to-console Controls whether the enforcer’s logs are written to stdout. Boolean that defaults to false.
--namespace ENFORCERD_NAMESPACE The Microsegmentation namespace the enforcer should register in.
--persist-credentials Pass this flag or set the environment variable to true if you are using the Advanced on-premise install and wish to persist the enforcer’s app credential on disk. Defaults to false.
--tag Microsegmentation tag for this enforcer
--token ENFORCERD_TOKEN Microsegmentation token for the enforcer to use to register to the Microsegmentation Console.
--working-dir A persistent working directory with write, read, and execute permissions. Files such as logs are stored here. Defaults to %PROGRAMDATA%\enforcerd