2021-11-17: With the archiving of the clj-symphony
and symphony-java-client
libraries that this bot depends upon, this project is now also archived. Clojure developers who wish to develop Symphony bots are encouraged to evaluate symphony-java-toolkit
, a high quality open source successor to the symphony-java-client
.
A small Symphony bot that attempts to execute messages sent to it as Clojure code, in a secure sandbox. Heavily inspired by verma/clj-slackbot.
For now Clojure bot is available in source form only, so fire up your favourite git client and get cloning!
Clojure bot is configured via a single, optional EDN file that may be specified on the command line via the "-c" command line option. You can also provide a "-h" command line option to get help on all of the command line options the bot supports.
The configuration file is traditionally called config.edn
(but may be called anything you like) and may be stored anywhere
that can be read by the bot's JVM process via standard POSIX file I/O. It's loaded using the aero
library - see the aero documentation for details on the various advanced
options aero supports.
The bot ships with a default config.edn
file
that will be read if a config file is not specified on the command line. This file delegates basically all configuration to
environment variables, allowing the administrator to deploy and run the bot as a standalone uberjar, and configure it exclusively
from the runtime environment.
Please refer to the default config.edn
file
for details on using these environment variables. Their use is not described here.
The bot's configuration includes sensitive information (certificate locations and passwords), so please be extra careful to secure this configuration, however you choose to manage it (in a file, environment variables, etc.).
The configuration file is structured as follows:
{
:symphony-coords {
:pod-id "<id of pod to connect to - will autopopulate whichever of the 4 URLs aren't provided. (optional - see below)>"
:session-auth-url "<the URL of the session authentication endpoint. (optional - see below)>"
:key-auth-url "<The URL of the key authentication endpoint. (optional - see below)>"
:agent-api-url "<The URL of the agent API. (optional - see below)>"
:pod-api-url "<The URL of the Pod API. (optional - see below)>"
:trust-store ["<path to Java truststore>" "<password of truststore>"]
:user-cert ["<path to bot user's certificate>" "<password of bot user's certificate>"]
:user-email "<bot user's email address>"
}
:jolokia-config {
"host" "<jolokia-server-host>"
"port" "<jolokia-server-port-as-a-string>"
}
:evaluation-timeout <seconds> ; Optional - defaults to 10 seconds
:accept-connections-interval <minutes> ; Optional - defaults to 30 minutes
:admin-emails ["user1@domain.tld" "user2@domain.tld"] ; Optional
}
The coordinates of the various endpoints, certificates, knickknacks and geegaws that the bot needs in order to connect to a
Symphony pod. This map is passed directly to the
clj-symphony library's connect
function,
and has the same semantics as what's described there.
The configuration of the Jolokia library, used to support server-side ops monitoring of the bot.
This map is passed directly to Jolokia's JolokiaServerConfig
constructor.
See the default Jolokia property file
for a full list of the supported configuration options and their default values, and note that all
keys and values in this map MUST be strings (this is a Jolokia requirement).
Timeout (in seconds) for evaluating Clojure forms. Optional and defaults to 10 seconds.
The interval (in minutes) that the bot will use to check for and accept incoming cross-pod connection requests. If not specified, defaults to 30 minutes.
A list of administrator email addresses. These users will be able to interact with the bot via ChatOps (1:1 chats with the bot
in Symphony). Administrators should say help
to the bot to get a list of the available admin commands.
This bot leverages the clojails Clojure sandboxing library, which in turn leverages
Java's security manager capability. Because the
Java security manager mechanism is JVM-global, you must provide a Java security policy file in the startup parameters for
the bot's JVM, or else it will fail with numerous java.security.AccessControlException: access denied
exceptions.
Note that the policy file you provide only applies to code running outside the clojail sandbox (the bot's own code). For this reason the sample policy file is deliberately lenient - this is the simplest way to ensure that all of the bot's code is allowed to function.
With that said, while clojail is well tested, there is always the possibility that code submitted to it will escape the sandbox. For this reason, in production environments it is recommended that the global policy file is carefully constructed, to provide defence in depth.
Contributions of stronger policy files that don't interfere with the operation of the bot would be very welcome!
Clojure bot uses the logback library for logging, and ships with a
reasonable default logback.xml
file.
Please review the logback documentation if you
wish to override this default logging configuration.
For now, you can run Clojure bot either directly or as a Docker image.
$ lein git-info-edn
$ lein run -- -c <path to EDN configuration file>
or
$ lein do git-info-edn, uberjar
...
$ java -jar ./target/bot-clj-standalone.jar -c <path to EDN configuration file>
To build the container:
$ docker build -t bot-clj .
To run the container:
$ # Interactively:
$ docker run -v /path/to/config/directory:/etc/opt/bot-clj:ro bot-clj
$ # In the background:
$ docker run -d -v /path/to/config/directory:/etc/opt/bot-clj:ro bot-clj
Where /path/to/config/directory
should be replaced with the fully qualified path of the configuration directory
on the Docker host. This configuration directory must contain:
- the service account certificate and truststore that the bot should use
- a
config.edn
file (in the format described above), that points to the certificates using/etc/opt/bot-clj
as the base path (that's where the configuration folder is mounted within the container)
And it may optionally also contain:
- blacklist files (see above for details)
- a logback configuration file
You can also use Docker Compose, by running:
$ docker-compose up -d
This assumes that the etc
directory contains the certificate, truststore, and config.edn
file, as described above.
Copyright 2017 Fintech Open Source Foundation
Distributed under the Apache License, Version 2.0.
SPDX-License-Identifier: Apache-2.0
To see the full list of licenses of all third party libraries used by this project, please run:
$ lein licenses :csv | cut -d , -f3 | sort | uniq
To see the dependencies and licenses in detail, run:
$ lein licenses