# KEYCHEST Agent (keychest_agent)
  
## Lightweight agent for internal network audits  
  
Copyright (C) Smart Arcs Ltd, registered in the United Kingdom.  
Unauthorized copying of this file, via any medium is strictly prohibited  
  
### Function
 
keychest_agent is a lightweight Python proxy for management of intranet encryption keys with a control enforced via its local configuration file.  
  

### Installation
 
1. `keychest_agent --register` - an optional parameter (`--staging`); this command will print the agent's registration ID in the form of `<random string>@keychest.net`
2. run `keychest_agent` as a daemon using a supervisor or other tool ensuring it is restarted if it terminates.
3. register the agent's ID in your KeyChest account so you can define its audit scope.
  
### Operational Files
  
`keychest_agent` creates a set of files in the $HOME folder of the effective user. All its files are in a folder `.keychest`. The file structure follows a Linux file structure with:
 - `var/log/keychest_agent` - for log files  
 - `etc/keychest_agent` - configuration files  
 - `var/sock` - a sock file for multiprocessing logging module  
 - `var/run` - runtime related files  

  
### Overview 
  
The core of KeyChest agents comprises the following 3 subsystems:  
  
1. **Logging** - a robust logging, which stores activity logs locally as well as posts them to the KeyChest service is simply a must for efficient management. Detailed information is what you need when in trouble - whether it's for KeyChest users or for our support helping you out.
2. **Proxy operation** - the actual audit of secure services requires a strong control over the networking, something that is platform dependent and we are regularly updating it. It means agents must work as transparent proxies for traffic generated by the KeyChest Audit Engines.
3. **Local control** - agents are gateways into your internal networks and we want to give you as much control as possible over what they can be used for. We are putting restrictions on the ports they can connect to, the address ranges they can use, and so on. This information is in local configuration files, which can be locked-down so only you can change them. We also plan to give as wide access to the source codes of agents as possible.  

  
### Proxy Operation
  
Each agent controls the traffic and any requests coming from the [KeyChest.net](https://keychest.net)  service. Details of audit requests are sent to agents so they can block those not complying with agent's local configuration file.  
  
Agents regularly connect to keychest.net to request audit "jobs". When they receive a valid description of an audit job, they will launch a proxy, which connects to the audit target (downstream) and to KeyChest (upstream). Once the audit is completed, the proxy is terminated and the agent can re-use its port.  
  
Internal network discovery is treated separately. We plan to implement a range of discovery methods based either on:  
  
1. internal database of certificates (e.g., LDAP storage of your PKI system); or  
2. internal DNS zone.  
  
Discovered services are sent to the KeyChest service so it can start scheduling regular audits.  

  
### Links
  
1. more info - https://keychest.net/stories/keychest-unifying-public-and-private-keys  
2. support - support@keychest.net  
3. KeyChest's founder blog - https://magicofsecurity.com
