{"_id":"55dc76036f16451700843e0c","githubsync":"","parentDoc":null,"user":"55dc702d7fa0290d00559106","category":{"_id":"55dc751b00a8811900c230e3","pages":["55dc75b27fa0290d00559123","55dc75c055be9f21004ee24e","55dc75ef00a8811900c230e7","55dc76036f16451700843e0c","55dc760e00a8811900c230e9","55dc767d55be9f21004ee251","55df5db386ae7f0d00db4ccd","55df64cfaf76b70d0060a60e","55df7263c59b180d005fa70e","55e0b72fa44fae0d002148c5","55e0c42b5087cb1900986c0f","55e36b1bac4eef230079a735","55f363ea2d3bae21009c47aa","55f36bcc5f8674370067b73c","55f36c23ec46040d0030326a","5605d2eda4574a0d00811346","560ac5fef6994b0d0023bca6","561be02937781d0d007942b0","56782f0048c8d00d0094b7fc"],"project":"55db8f8f1a91690d007ad975","version":"55db8f901a91690d007ad978","__v":19,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-08-25T14:00:59.500Z","from_sync":false,"order":1,"slug":"how-to-get-started","title":"Agent Installation"},"version":{"_id":"55db8f901a91690d007ad978","project":"55db8f8f1a91690d007ad975","__v":17,"createdAt":"2015-08-24T21:41:36.034Z","releaseDate":"2015-08-24T21:41:36.034Z","categories":["55db8f901a91690d007ad979","55db9856b3d6540d00886426","55dc751b00a8811900c230e3","55dc766255be9f21004ee250","55dc769200a8811900c230ed","55e4c701177b6e0d003330fa","55f4915caf0bc71900a53130","55f491b2be9c2b2100f0635d","560b22739c7be70d00100bd8","57488c53e8c6a420000b729c","574cefd95953e20e00f40f9f","5798edfd7700d30e00ad250c","579ac88234b5fd0e00b9e140","57c81c6d690c200e0047b72e","57d9b8fbda17c30e003897f1","57d9b90e608ea00e00f358d8","57d9b91cda17c30e003897f4"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"project":"55db8f8f1a91690d007ad975","__v":44,"updates":["57bb0e875c849b1700f1e525","57bcb744e0720519008ced85","57fd393f46157e0e00f09c8b","5a99962620047e00126ff3c8"],"next":{"pages":[],"description":""},"createdAt":"2015-08-25T14:04:51.003Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":3,"body":"[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/1gWzKvUTSgOGNUN50381_java-logo-46361_943x345.png\",\n        \"java-logo-46361_943x345.png\",\n        \"943\",\n        \"345\",\n        \"#127abe\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Supported Versions\"\n}\n[/block]\nJava: 6, 7, 8\nOS: Windows, Linux or OS X 10.11, 64-bit only\nWeb Server: One of the following:\n* Apache Tomcat: Version 7, 8, or 9\n* Jetty: Version 8 or 9\n* WebSphere: Version 8.5 or 9\n\n<br>\nFor Application Frameworks:\n * Spring Framework >= 3.2\n * Struts Framework >= 2.3\n\nFor SQL Injection Protection:\n* MySQL >= 5.0.5, PostgreSQL >= 9.1, Oracle (JDBC 4), HSQLDB >= 1.8, H2 >= 1.4\n\nFor Cross-Site Scripting Protection:\n* Apache Jasper (JSP) version 2\n\nFor Authentication Protection:\n* Spring Security version 3 or 4\n\nFor Open Redirect Protection:\n* Spring version 3.2 or 4\n\nFor CSRF Tampering Detection:\n* Spring Security version 3.2 or 4\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Prerequisites\"\n}\n[/block]\nThe IMMUNIO agent communicates with a management service at https://agent.immun.io. Ensure outbound access to this address is unblocked.​\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Installation\"\n}\n[/block]\nThe IMMUNIO agent comes in the form of a JAR file you can download it [here](https://download.immun.io/java/immunio-2.1.2.jar). \n\nThe agent must be added to the command line of the java runtime. For example, for version x.y.z of the agent, the following option must be added to the java command line arguments:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"java ... -javaagent:immunio-x.y.z.jar\",\n      \"language\": \"shell\",\n      \"name\": \"Command line argument\"\n    }\n  ]\n}\n[/block]\nEach web server has a different mechanism for adding command line arguments.\n\n## Jetty\nWhen using the Jetty server, export the following environment variable:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"export JAVA_OPTIONS=\\\"${JAVA_OPTIONS} -javaagent:/full/path/to/immunio-x.y.z.jar\\\"\",\n      \"language\": \"shell\",\n      \"name\": \"Jetty\"\n    }\n  ]\n}\n[/block]\n## Tomcat\nWhen using the Tomcat web server, export the following environment variable:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"export CATALINA_OPTS=\\\"${CATALINA_OPTS} -javaagent:/full/path/to/immunio-x.y.z.jar\\\"\",\n      \"language\": \"text\",\n      \"name\": \"Tomcat\"\n    }\n  ]\n}\n[/block]\n\n## Netty\nWhen using the Netty server, export the following environment variable:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"export JAVA_OPTS=\\\"${JAVA_OPTS} -javaagent:/full/path/to/immunio-x.y.z.jar\\\"\",\n      \"language\": \"shell\",\n      \"name\": \"Netty\"\n    }\n  ]\n}\n[/block]\n## WebSphere\nWhen using the WebSphere server, the javaagen JVM option adding the immunio agent jar file is configured in the Generic JVM options. e.g.:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/020768d-Screen_Shot_2018-02-07_at_11.02.44_AM.png\",\n        \"Screen Shot 2018-02-07 at 11.02.44 AM.png\",\n        924,\n        240,\n        \"#b9d3f6\"\n      ]\n    }\n  ]\n}\n[/block]\nFor more information on configuring agents with WebSphere, refer to[ IBM's WebSphere configuration documentation](http://www-01.ibm.com/support/docview.wss?uid=swg21417365) \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Configuration\"\n}\n[/block]\nThere are three ways to perform agent configuration: adding settings to an `immunio.properties` file, starting your application with command line options, or setting environment variables at runtime. Each is described below:\n\n## Properties File\nThe IMMUNIO agent will look in​ the following locations for the configuration file:\n\n  * A file location specified via the `io.immun.config.file` system property. System properties are generally set using `-D` command line options. For example: `-Dio.immun.config.file=/path/to/immunio.properties`.\n \n  * `immunio.properties` in the same directory as the IMMUNIO agent jar file.\n \n  * `immunio.properties` in the resources of your project.\n \nThe first location found will be used. Here is an example `immunio.properties` file:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"key = 87637d4f-f01a-406d-b3e6-1ff8f84a3d34\\nsecret = a0ca4263-da57-45f5-aabb-b72e5a78b510\\ncodeProtectionPluginsEnabled = true\",\n      \"language\": \"text\",\n      \"name\": \"immunio.properties\"\n    }\n  ]\n}\n[/block]\n## Command Line Options\nSettings may be configured at the command line interface using system properties. The system property name is formed by prepending `io.immun.` to the configuration setting. For example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"java ... \\\\\\n-Dio.immun.key=87637d4f-f01a-406d-b3e6-1ff8f84a3d34 \\\\\\n-Dio.immun.secret=a0ca4263-da57-45f5-aabb-b72e5a78b510 \\\\\\n-Dio.immun.codeProtectionPluginsEnabled=true \\\\\\n...\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\nThe method for setting command line options varies by web server. You may be able to pass them using the `-javaagent` command line argument as described above.\n\n## Environment Variables\nWhen using environment variables, convert setting names to uppercase and prepend `IMMUNIO_`. For example, the key would be provided in the environment variable `IMMUNIO_KEY`​.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"export IMMUNIO_KEY=87637d4f-f01a-406d-b3e6-1ff8f84a3d34\\nexport IMMUNIO_SECRET=a0ca4263-da57-45f5-aabb-b72e5a78b510\\nexport IMMUNIO_CODE_PROTECTION_PLUGINS_ENABLED=true\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Account Takeover Configuration\",\n  \"body\": \"If you do not plan to use IMMUNIO's Code Protection features, you can exclude the codeProtectionPluginsEnabled setting or set it to false.\"\n}\n[/block]\n## Multiple Immunio applications per JVM process\n\nYou can setup multiple apps under the same JVM process and agent. If your first app is installed under \"http://my-host.com:8080/app1\" and second under \"http://my-host.com:8080/app2\" for example, use:\n\n```\napp1.basePath = /app1\napp1.host = my-host.com\napp1.port = 8080\napp1.key = <Your Immun.io key for this app>\napp1.secret = <Your Immun.io secret for this app>\n\napp2.basePath = /app2\n# You can skip host and port to match any\napp2.key = <Your Immun.io key for this app>\napp2.secret = <Your Immun.io secret for this app>\n\n# Optionally, define a key and secret for requests that don't match any app\nkey = <Your Immun.io key for catching other requests>\nsecret = <Your Immun.io secret for catching other requests>\n```\n\nBy default, the agent will report all requests to the app on the dashboard corresponding to the `key` and `secret` defined at the root of the config file. If no `key` and `secret` are defined at the root, all unmatched requests will be ignored.\n\nAll app configurations (`app_name.*`) will take precedence over those defined at the root. The \"app_name\" must be unique to this app.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Verification\"\n}\n[/block]\nOnce the agent is installed and configured, start your application and send an HTTP request to it. Without that first HTTP call, the agent status will display INACTIVE in the dashboard. Within seconds of your first request, the agent should report in and change its status indicator to OK. Your app is now protected with IMMUNIO!​","excerpt":"","slug":"java","type":"basic","title":"Java"}
[block:image] { "images": [ { "image": [ "https://files.readme.io/1gWzKvUTSgOGNUN50381_java-logo-46361_943x345.png", "java-logo-46361_943x345.png", "943", "345", "#127abe", "" ] } ] } [/block] [block:api-header] { "type": "basic", "title": "Supported Versions" } [/block] Java: 6, 7, 8 OS: Windows, Linux or OS X 10.11, 64-bit only Web Server: One of the following: * Apache Tomcat: Version 7, 8, or 9 * Jetty: Version 8 or 9 * WebSphere: Version 8.5 or 9 <br> For Application Frameworks: * Spring Framework >= 3.2 * Struts Framework >= 2.3 For SQL Injection Protection: * MySQL >= 5.0.5, PostgreSQL >= 9.1, Oracle (JDBC 4), HSQLDB >= 1.8, H2 >= 1.4 For Cross-Site Scripting Protection: * Apache Jasper (JSP) version 2 For Authentication Protection: * Spring Security version 3 or 4 For Open Redirect Protection: * Spring version 3.2 or 4 For CSRF Tampering Detection: * Spring Security version 3.2 or 4 [block:api-header] { "type": "basic", "title": "Prerequisites" } [/block] The IMMUNIO agent communicates with a management service at https://agent.immun.io. Ensure outbound access to this address is unblocked.​ [block:api-header] { "type": "basic", "title": "Installation" } [/block] The IMMUNIO agent comes in the form of a JAR file you can download it [here](https://download.immun.io/java/immunio-2.1.2.jar). The agent must be added to the command line of the java runtime. For example, for version x.y.z of the agent, the following option must be added to the java command line arguments: [block:code] { "codes": [ { "code": "java ... -javaagent:immunio-x.y.z.jar", "language": "shell", "name": "Command line argument" } ] } [/block] Each web server has a different mechanism for adding command line arguments. ## Jetty When using the Jetty server, export the following environment variable: [block:code] { "codes": [ { "code": "export JAVA_OPTIONS=\"${JAVA_OPTIONS} -javaagent:/full/path/to/immunio-x.y.z.jar\"", "language": "shell", "name": "Jetty" } ] } [/block] ## Tomcat When using the Tomcat web server, export the following environment variable: [block:code] { "codes": [ { "code": "export CATALINA_OPTS=\"${CATALINA_OPTS} -javaagent:/full/path/to/immunio-x.y.z.jar\"", "language": "text", "name": "Tomcat" } ] } [/block] ## Netty When using the Netty server, export the following environment variable: [block:code] { "codes": [ { "code": "export JAVA_OPTS=\"${JAVA_OPTS} -javaagent:/full/path/to/immunio-x.y.z.jar\"", "language": "shell", "name": "Netty" } ] } [/block] ## WebSphere When using the WebSphere server, the javaagen JVM option adding the immunio agent jar file is configured in the Generic JVM options. e.g.: [block:image] { "images": [ { "image": [ "https://files.readme.io/020768d-Screen_Shot_2018-02-07_at_11.02.44_AM.png", "Screen Shot 2018-02-07 at 11.02.44 AM.png", 924, 240, "#b9d3f6" ] } ] } [/block] For more information on configuring agents with WebSphere, refer to[ IBM's WebSphere configuration documentation](http://www-01.ibm.com/support/docview.wss?uid=swg21417365) [block:api-header] { "type": "basic", "title": "Configuration" } [/block] There are three ways to perform agent configuration: adding settings to an `immunio.properties` file, starting your application with command line options, or setting environment variables at runtime. Each is described below: ## Properties File The IMMUNIO agent will look in​ the following locations for the configuration file: * A file location specified via the `io.immun.config.file` system property. System properties are generally set using `-D` command line options. For example: `-Dio.immun.config.file=/path/to/immunio.properties`. * `immunio.properties` in the same directory as the IMMUNIO agent jar file. * `immunio.properties` in the resources of your project. The first location found will be used. Here is an example `immunio.properties` file: [block:code] { "codes": [ { "code": "key = 87637d4f-f01a-406d-b3e6-1ff8f84a3d34\nsecret = a0ca4263-da57-45f5-aabb-b72e5a78b510\ncodeProtectionPluginsEnabled = true", "language": "text", "name": "immunio.properties" } ] } [/block] ## Command Line Options Settings may be configured at the command line interface using system properties. The system property name is formed by prepending `io.immun.` to the configuration setting. For example: [block:code] { "codes": [ { "code": "java ... \\\n-Dio.immun.key=87637d4f-f01a-406d-b3e6-1ff8f84a3d34 \\\n-Dio.immun.secret=a0ca4263-da57-45f5-aabb-b72e5a78b510 \\\n-Dio.immun.codeProtectionPluginsEnabled=true \\\n...", "language": "shell" } ] } [/block] The method for setting command line options varies by web server. You may be able to pass them using the `-javaagent` command line argument as described above. ## Environment Variables When using environment variables, convert setting names to uppercase and prepend `IMMUNIO_`. For example, the key would be provided in the environment variable `IMMUNIO_KEY`​. [block:code] { "codes": [ { "code": "export IMMUNIO_KEY=87637d4f-f01a-406d-b3e6-1ff8f84a3d34\nexport IMMUNIO_SECRET=a0ca4263-da57-45f5-aabb-b72e5a78b510\nexport IMMUNIO_CODE_PROTECTION_PLUGINS_ENABLED=true", "language": "shell" } ] } [/block] [block:callout] { "type": "info", "title": "Account Takeover Configuration", "body": "If you do not plan to use IMMUNIO's Code Protection features, you can exclude the codeProtectionPluginsEnabled setting or set it to false." } [/block] ## Multiple Immunio applications per JVM process You can setup multiple apps under the same JVM process and agent. If your first app is installed under "http://my-host.com:8080/app1" and second under "http://my-host.com:8080/app2" for example, use: ``` app1.basePath = /app1 app1.host = my-host.com app1.port = 8080 app1.key = <Your Immun.io key for this app> app1.secret = <Your Immun.io secret for this app> app2.basePath = /app2 # You can skip host and port to match any app2.key = <Your Immun.io key for this app> app2.secret = <Your Immun.io secret for this app> # Optionally, define a key and secret for requests that don't match any app key = <Your Immun.io key for catching other requests> secret = <Your Immun.io secret for catching other requests> ``` By default, the agent will report all requests to the app on the dashboard corresponding to the `key` and `secret` defined at the root of the config file. If no `key` and `secret` are defined at the root, all unmatched requests will be ignored. All app configurations (`app_name.*`) will take precedence over those defined at the root. The "app_name" must be unique to this app. [block:api-header] { "type": "basic", "title": "Verification" } [/block] Once the agent is installed and configured, start your application and send an HTTP request to it. Without that first HTTP call, the agent status will display INACTIVE in the dashboard. Within seconds of your first request, the agent should report in and change its status indicator to OK. Your app is now protected with IMMUNIO!​