1. General Troubleshooting Steps

1.1. Agent Fails to Install

Symptoms:

• Installer does not complete.
• Error messages, e.g., "Permission denied."

Resolutions:

• Ensure Admin Rights:
  • Install with administrator privileges.
  • On Windows, right-click the installer and select Run as Administrator.
• Verify Prerequisites:
  • Windows: Ensure .NET Framework 4.8+ is installed.
  • Mac: Grant Full Disk Access in System Preferences > Privacy & Security > Full Disk Access.
  • Linux: Confirm dependencies like python3, pip, ping3, and pysmb are installed.
• Review Logs for Errors:
  • Windows: C:\CYRISMA_Agent\logs\CYRISMA_Agent_Install.log
  • Mac: /var/log/install.log
  • Linux: /var/log/syslog

1.2. Agent Does Not Appear in the CYRISMA Command Center

Symptoms:

• Installed agent does not show under Admin > Scan Agents.

Possible Causes:

• Missing or incorrect installation key and URL.
• Network connectivity issues.

Resolutions:

• Verify CYRISMA Key and URL:
  • Confirm the key and URL under Admin > Scan Agents > Agent Download.
• Check Network Connectivity:
  • Test connectivity to cyrisma.com and the specific instance URL.
  • Allow outbound communication through firewalls and content filters.
• Restart the Agent Service:
  • Windows: Restart the CYRISMA_Agent service via services.msc.
  • Mac/Linux: Use launchctl or systemctl.

1.3. Provisioning Issues

Symptoms:

• Agent installed but not provisioned.
• Agent appears in New Agent but cannot be approved.

Resolutions:

• Verify Service Account Credentials:
  • Ensure the account used for network scans has admin rights on all target machines.
  • Avoid using passwords with unsupported special characters (only @!()-_ are allowed).
• Re-Provision the Agent:
  • Navigate to Admin > Scan Agents > New Agent, select the agent, and re-enter credentials if prompted.

2. Platform-Specific Troubleshooting

2.1. Windows Installation Issues

Symptoms:

• Installer exits unexpectedly.
• Agent service fails to start.

Resolutions:

• Install .NET Framework 4.8+:
  • Download and install the required framework.
• Exclude Files/Directories from Antivirus:
  • Add exclusions for:

C:\CYRISMA_Agent\DataSpotliteAgent.exe
C:\CYRISMA_Agent\App\psexec.exe
C:\CYRISMA_Agent

• Command-Line Deployment for Bulk Installations:
  • Use the following syntax:

Cyrisma_Setup.exe /verysilent /key=XXXX-XXXX /url=https://ccXXXXXX.cyrisma.com

2.2. Mac Installation Issues

Symptoms:

• Permissions-related errors.
• Agent not checking in after installation.

Resolutions:

• Grant Full Disk Access:
  • Go to System Preferences > Security & Privacy > Privacy > Full Disk Access and add the installer.
  • Restart Terminal after making changes.
• Ensure Correct Package for Architecture:
  • Intel-based Macs: CyBroker_Installer.pkg
  • M1/M2 Macs: CyBroker_Installer_Arm64.pkg
• Validate Environment Variables:
  • For SIP-enabled Macs, create a cyrisma_env.txt file in /tmp:

echo "CY_KEY=XXXX-XXXX" > /tmp/cyrisma_env.txt
echo "CY_URL=https://ccXXXXXX.cyrisma.com" >> /tmp/cyrisma_env.txt

• Run the installer with:

sudo installer -pkg CyBroker_Installer.pkg -target /

2.3. Linux/Debian Installation Issues

Symptoms:

• Dependencies not installed.
• Agent fails to start or provision.

Resolutions:

• Run Installation from /tmp:
  • Move the .deb package to /tmp:

sudo mv ~/Downloads/CyBroker_Linux_Installer.deb /tmp
cd /tmp
sudo apt install -y ./CyBroker_Linux_Installer.deb

• Verify Dependencies:
  • Install dependencies if not already present:

sudo apt install -y python3 python3-pip
pip install ping3 pysmb

• Restart the Agent Service:

sudo systemctl restart CYRISMA_Agent

• Logs and Errors:
  • Check /var/log/syslog for installation and runtime errors.

3. Remote Deployment Troubleshooting

3.1. PowerShell Deployment Issues

Symptoms:

• Script fails to deploy agents.

Resolutions:

• Verify Script Syntax:
  • Ensure variables are set correctly:

$args="/verysilent /key=XXXX /url=https://ccXXXXX.cyrisma.com"

• Network and Permissions:
  • Ensure admin credentials are used and script execution is allowed.

3.2. Group Policy Deployment Issues

Symptoms:

• Agents fail to install via GPO.

Resolutions:

• Validate GPO Configuration:
  • Check that the deployment script is linked correctly to the GPO.
• Ensure Script Path Matches Deployment Location:
  • Confirm the script’s location in netlogon matches the path in the GPO.

4. Endpoint Protection and Firewall Issues

• Firewall Settings:
  • Allow outbound connections to cyrisma.com and related IPs.
• Antivirus Configuration:
  • Add exclusions for:

C:\CYRISMA_Agent\
DataSpotliteAgent.exe
psexec.exe

5. Common Errors and Resolutions

6. FAQs

Q: Why isn’t the agent communicating with the Command Center?

• Check the key and URL.
• Ensure firewall and network connectivity allow access to CYRISMA.

Q: How do I fix permissions issues on Mac?

• Grant Full Disk Access to the installer and restart the terminal.

Q: What if agents fail to provision?

• Check service account credentials and ensure admin rights on target machines.

For further assistance, contact CYRISMA Support.