Agent registration issues

Overview

Incydr collects file activity from agents installed on devices and reports it in the Incydr console for review and investigation. However, if an agent is not successfully registered with Incydr, file activity cannot be collected. Use the information on the Agent registration issues screen to resolve problems with agent registration and resume data collection. 

Agent registration issues in the Incydr console

To view agent registration issues:

1. Sign in to the Incydr console.
2. Select Administration > Status > Agent Registration Issues.

Item		Description
a	Export	Export the filtered events to a comma-separated values (CSV) file.
b	Filter	Filter the events by the criteria you select.
c	Filtered by	The filters that are currently applied. Click the X to remove that filter. Remove all filters to view all agent registration issues.
d	Attempt date	The date registration was attempted. Typically, registration is attempted when the agent is first installed. Only agents with registration issues in the last 30 days appear in the list.
e	Registration issue	The issue preventing successful registration. For issue descriptions and solutions, see Recommended solutions below.
f	Hostname	The name of the device as reported by the device's operating system. The Hostname is a device property that is not managed by Incydr. If an authorized user changes the hostname of the device, the new hostname may take up to 24 hours to update in the Incydr console.
g	Operating system	Operating system for the device where the agent is installed.
h	Registration username	The username the agent is registered under.
i	View details	View details of the registration attempt.

Export

Click Export to export the filtered issues and parameters to a comma-separated values (CSV) file. Any filters that are applied are shown above the agent registration issues list. Click the X on a filter to remove that filter from the exported results.

Filter

Click Filter to filter the issues listed in Agent registration issues. When you click Apply, issues that match all filters appear in the list.

Item		Description
a	Registration issue	Select registration problems to search for. For issue descriptions and solutions, see Recommended solutions below.
b	Hostname	Type a device hostname to add to the filter.
c	Registration username	Type a username to add to the filter.
d	Cancel / Apply	Click Apply to apply the selected filter criteria to the list and display only the issues that match that criteria. To return to the list without applying any filters, click Cancel.

Registration attempt

Click View details to view details of a registration attempt. 

Item		Description
a	Registration attempt	Displays the date and issue of the registration attempt. For issue descriptions and solutions, see Recommended solutions below.
b	User	Displays the username the agent is registered under.
c	Organization	Displays the organization, organization's registration key, and deployment policy the agent was registered under.
d	Device information	Displays device information, including operating system and IP address.

Troubleshoot agent registration issues

Diagnose issues

Agents register automatically at deployment, provided no issues prevent them from registering. If any issues occur in the registration process itself, the issue appears on the Agent registration issues screen for troubleshooting.

To troubleshoot registration issues that require attention: 

1. Sign in to the Incydr console.
2. Select Administration > Status > Agent Registration Issues.
3. Click Filter to filter the list by Registration issue(s), Hostname, and Registration username.
4. Select an issue in the list to view details about the unsuccessful registration attempt.
5. Steps to resolve the issues with the agent registration vary, depending on the issue. See Recommended solutions below for complete information about registration issues and steps to resolve them. 

Recommended solutions

The following issues can appear on the Agent registration issues screen in the Incydr console. Complete the recommended steps to correct the issue.

Blocked organization

The organization the agent was deployed to as set by the deployment policy is blocked. Unblock the organization and redeploy agents. Alternatively, change the user's organization to one that is unblocked, and redeploy agents.

Deactivated organization

The organization the agent was deployed to as set by the deployment policy is deactivated. Reactivate the organization and redeploy agents. Alternatively, change the user to an organization that is activated, and redeploy agents.

Deactivated user

The username associated with the agent is deactivated. Reactivate the user to complete the registration.

Deployment secret not found

The deployment secret for the policy used to deploy the agent is not recognized. Check the deployment secret used to deploy the agent. If needed, generate a new deployment secret and redeploy agents.

Expired deployment secret

The deployment secret for the policy used to deploy the agent is expired. Extend the expired deployment secret and redeploy agents. 

No username

The username associated with the agent is not found in Incydr. Adjust the user detection script in the deployment policy to correctly acquire usernames from a source (such as a directory service) and redeploy agents.

Registration key not found

The registration key for an organization is not found. Ensure your user licenses are up-to-date. Once licensing is corrected, and organizations have active registration keys, redeploy agents. 

Unknown cause

The cause for the registration issue is undetermined. Examine the organization, deployment policy, user, and device associated with the issue shown on the Registration attempt screen to determine a cause.

User provisioned with registration

The user was not provisioned from a provisioning provider before registration was attempted. Reconfigure provisioning to run again, then redeploy agents. 

Username requires email format

The username does not have email format. All users in Incydr must have their username in email format. Adjust the user detection script in the deployment policy to correctly acquire usernames from a source (such as a directory service) and place them into email format, and redeploy agents.

Username taken

The username associated with the agent is already in use. Update the username to be unique.

Review additional agent status details via the command-line

Requires insider risk agent version 2.2.0 or later

From the command-line or your MDM, use the commands below to return JSON-formatted details about an agent:

• Mac: sudo /Applications/Code42-AAT.app/Contents/MacOS/code42-aat-cli status
• Windows MDM: "C:\Program Files\Code42-AAT\code42-aat-cli.exe" status
• Windows Powershell: Start-Process -FilePath "C:\Program Files\Code42-AAT\code42-aat-cli.exe" -ArgumentList "status"
• Linux: /opt/code42-aat/bin/code42-aat-cli status

Details include: agent state, the last time settings were retrieved from the cloud, the last time security events were sent to the cloud, macOS full disk access and accessibility permission settings, and more.

Re-register agents via the command-line

From the command-line or your MDM, use the commands below to re-register an agent and rerun the user detection script.

Configuration options

• If you are not using uninstall secrets, omit the /s or -s option.
• To rerun the existing user detection script, omit the PROVIDED_USERNAME=<useremail> parameter.
• To register as a specific user, include the PROVIDED_USERNAME=<useremail> parameter.

Sample commands

• Mac: sudo /Applications/Code42-AAT.app/Contents/MacOS/code42-aat-cli register -d DEPLOYMENT_URL=<deployment URL>,DEPLOYMENT_POLICY_TOKEN=<Deployment policy Token>,DEPLOYMENT_SECRET=<Deployment Secret>,PROVIDED_USERNAME=<username> -s <secret>
• Windows MDM: "C:\Program Files\Code42-AAT\code42-aat-cli.exe" register /d "DEPLOYMENT_URL=<deployment_url>,DEPLOYMENT_POLICY_TOKEN=<deployment_policy_token>,DEPLOYMENT_SECRET=<deployment_secret>,PROVIDED_USERNAME=<useremail>" /s <agent_uninstall_secret>
• Windows Powershell: Start-Process -FilePath "C:\Program Files\Code42-AAT\code42-aat-cli.exe" -ArgumentList "register /d DEPLOYMENT_URL=<deployment_url>,DEPLOYMENT_POLICY_TOKEN=<deployment_policy_token>,DEPLOYMENT_SECRET=<deployment_secret>,PROVIDED_USERNAME=<useremail>" /s <agent_uninstall_secret>

Related topics

• Identify and resolve device issues in the Incydr console
• Device Status report reference
• Monitor your Incydr environment health
• Monitor and improve Incydr environment health
• Use reports to monitor your environment