# Enterprise Agent (on-premise)

> Install the on-premise agent so cSquare can collect evidence from systems that never leave your network.

Source: https://docs.csquaregrc.com/connectors/enterprise-agent

The Enterprise Agent is a small program you run inside your own network. It makes
an outbound connection to cSquare, so you do not open any inbound firewall ports.
Once it is running, cSquare can collect evidence from systems that are not
reachable from the internet: Jira Server, Active Directory, SharePoint On-Prem,
Confluence Server, and network file shares.

## Before you start

- You need the workspace **owner** or **admin** role to register an agent.
- Pick a host that is always on and can reach the systems you want to connect.
- Outbound HTTPS access to cSquare is required. Nothing else needs to change.

## 1. Register the agent

Go to **Settings > Enterprise agents** and choose **Register agent**. Give it a
name that says where it runs, for example "London data centre". cSquare shows you
an agent ID and a one-time secret.

Copy the secret now. It is shown once and cannot be retrieved later. If you lose
it, revoke the agent and register a new one.

## 2. Download and install

Use the **Download agent** button on the same page. The bundle already contains
your agent ID and the cloud address; you only add the secret.

Docker is the quickest path:

```bash
unzip csquare-agent.zip && cd csquare-agent
# open .env and paste the secret next to CSQUARE_AGENT_SECRET
docker compose up -d
```

For a plain install, run `npm install` then `npm start` in the same folder.
On Windows, run the bundled service installer and enter the secret when prompted.

## 3. Confirm it is connected

Back in **Settings > Enterprise agents**, the agent shows **Connected** within a
minute of starting. The "Last seen" time updates every few minutes while it runs.

## 4. Add connectors

With the agent connected, open **Settings > Integrations** and add an on-premise
connector. Choose the agent you just registered as the route, then supply the
credentials for that system. Credentials are stored encrypted and are only used
by your own agent.

## Managing agents

- **Rename** an agent at any time; it does not interrupt collection.
- **Revoke** an agent to cut its access immediately. Evidence already collected
  stays in place.
- **Delete** removes a revoked agent and its connector rows from the list.

## When something goes wrong

**The agent stays "Never connected".** The secret is usually the cause. Check the
`.env` value has no trailing spaces, then restart. If it still fails, revoke the
agent and register a fresh one.

**It connects then drops every few minutes.** Something between the host and the
internet is closing idle connections. Allow long-lived outbound HTTPS from the
agent host, or exclude it from TLS inspection.

**A connector reports credential errors.** The agent is fine; the account it uses
for that system is not. Confirm the account still exists, is not locked, and has
read access to the data being collected.