Apache Hop Security Hardening with Practical Examples

Intro

Apache Hop security hardening turns a vulnerable default installation into a verified, repeatable secure state. The goal is not a checklist of theoretical risks; it is a sequence of practical steps that you can run against a real deployment, observe the result, and roll back if the change does not behave as expected.

This article is written for developers, DevOps consultants, and technical startup teams who operate Apache Hop 1.2.x or 2.x in a single-node or small-cluster deployment. The commands shown are deliberately simple, use placeholders for all environment-specific values, and include the verification step plus a recovery path. Nothing here should be run blindly. Capture the current state before changing anything, limit each change to one component, and confirm the outcome with a read-only observation or a documented log entry.

Apache Hop does not ship with authentication or authorization enabled by default. The embedded Hop Server (Carte) exposes a web UI and an XML-RPC API that accept unauthenticated requests unless you explicitly configure a user database and a security policy. Hardening means tightening those defaults in a controlled way: identify the installed version, inventory the current configuration, change one setting, verify the expected behavior, and have a tested rollback plan. This article covers four work areas: version and environment inventory, safe configuration changes, verification and diagnostics, and failure modes with recovery. Each section includes concrete commands and their expected output, using placeholder values like your-company, dev-team, and hop-server-01 that you replace with your own values.

Version and Environment Inventory

Before you can harden a Hop deployment, you must know exactly what you are running. The version of Hop, the Java runtime, the deployment topology (embedded vs. Carte server), and the location of key configuration files all affect which commands are safe to run and which security controls are available. For example, Hop 1.2.x stores its server configuration in config/hop-server.xml and uses the hop-server.sh (or .bat) launcher. Hop 2.x keeps the same file format but changes the default location of the metadata folder and introduces stricter validation. Running a Hop 2.x hardening step against a 1.2.x layout will fail silently or produce confusing errors.

Start with a read-only inventory of the installed version and the Java runtime. These commands do not change any state:

cd /opt/hop  # or your Hop home directory
./hop-run.sh --version
java -version

Expected output for Hop 2.1.0 on a supported JVM:

Apache Hop 2.1.0
openjdk version "17.0.9" 2023-10-17 LTS
OpenJDK Runtime Environment (build 17.0.9+8)
OpenJDK 64-Bit Server VM (build 17.0.9+8, mixed mode, sharing)

If the Hop version is 1.2.x, replace hop-run.sh with hop-run.bat on Windows or use the corresponding launcher. The inventory below assumes Hop 2.x; adjust the paths accordingly.

Next, identify the deployment topology. Hop can run as a standalone desktop application, as a Carte server (hop-server), or as a cluster of Carte nodes. The security surface differs: a desktop install usually has no remote API, while a Carte server exposes HTTP endpoints that must be protected. Ask three questions:

1. Is a Carte server running? (ps -ef | grep hop-server on Linux, or tasklist | findstr hop-server on Windows.)
2. Which port is the Carte server listening on? (Default is 8080; check the hop-server.xml for the <port> element or the -p launcher argument.)
3. Is the Hop GUI running with the embedded web server? (The Hop GUI can start a local Carte instance for testing; treat this as a server if it is reachable from other machines.)

Record the current state in a plain-text inventory file. An example for a typical single-node Carte deployment:

Host: hop-server-01
Hop version: 2.1.0
Java: OpenJDK 17.0.9
Deployment: Carte server, port 8080
Config file: /opt/hop/config/hop-server.xml
Users file: /opt/hop/config/hop-users.xml (if exists)
Observed on: 2025-03-21 14:30 UTC

This inventory gives you a baseline for every later change. If a hardening step breaks something, you can compare the current state against this recorded snapshot and roll back to the exact file copy.

Prerequisites for this section: access to the Hop installation directory, permission to view configuration files, and a shell session on the host. None of these commands modify the system.

Blast radius: read-only commands have zero blast radius. The inventory file you create is local to your working directory; do not add it to version control unless it contains no secrets.

Verification: the hop-run.sh --version output should match your expected release line. The java -version output should show a supported LTS version (11 or 17 for Hop 2.x; 8 or 11 for Hop 1.2.x). A mismatch is a warning to stop and resolve before proceeding.

Recovery: no recovery is needed. If you accidentally overwrite the inventory file, recreate it from the same read-only commands.

Safe Configuration Path

The main hardening changes for a Hop Carte server are: enabling authentication, replacing default passwords, and restricting the XML-RPC API to necessary methods. Each change should be made one at a time, with a verification step before moving to the next.

1. Enable Authentication on the Carte Server

Hop's Carte server reads its security settings from the hop-server.xml file. By default, the file contains an empty <authorization> element, meaning any HTTP request is accepted. Enabling authentication requires adding a user database and a security policy.

Step 1: Back up the current server configuration.

cp config/hop-server.xml config/hop-server.xml.bak-20250321

Step 2: Create a password file for the built-in user database. Hop 2.x provides the hop-encrypt.sh utility to generate hashed credentials. For example, create a user admin with a strong password (replace YourStrongPassword! with a real passphrase):

./hop-encrypt.sh -u admin -p 'YourStrongPassword!' -o config/hop-users.xml

Expected output:

User 'admin' written to config/hop-users.xml

The generated file contains a salted SHA-256 hash, not the plaintext password. Never edit this file by hand.

Step 3: Edit config/hop-server.xml to reference the user file and enable authorization. Add the following XML inside the <hop-server-config> element, replacing the empty <authorization/> if present:

<authorization>
  <users-file>config/hop-users.xml</users-file>
  <authentication-method>basic</authentication-method>
</authorization>

This tells the Carte server to use HTTP Basic authentication with the credentials stored in hop-users.xml.

Step 4: Restart the Carte server to apply the change.

./hop-server.sh -p 8080

Step 5: Verify that unauthenticated access is now rejected. Use curl against the server's status endpoint (replace hop-server-01 with your host):

curl -v http://hop-server-01:8080/kettle/status

Expected result: HTTP 401 Unauthorized, with a WWW-Authenticate header. A successful response without credentials means the authentication change did not take effect.

2. Replace Default Passwords and Restrict Users

If your Hop installation came with a preset user database or example users (e.g., from a bundled configuration), remove them or change their passwords immediately. A common pitfall is leaving the default cluster user with a known password. Use the same hop-encrypt.sh utility to update or remove users.

To remove a user:

./hop-encrypt.sh --remove-user cluster -f config/hop-users.xml

To change a password for an existing user:

./hop-encrypt.sh -u cluster -p 'NewSecurePassword!2' -f config/hop-users.xml

Verify the user list after the change:

./hop-encrypt.sh --list-users -f config/hop-users.xml

Expected output:

Users in config/hop-users.xml:
admin (enabled)

Any user not actively needed for automation should be removed. For scheduled jobs that call the Carte API, create a dedicated service account with the minimum required permissions (see next section).

3. Restrict XML-RPC API Methods

Hop's Carte server exposes a broad set of XML-RPC methods that can start, stop, and modify pipelines and workflows. Not all methods are needed in every deployment. To reduce the attack surface, configure the server to allow only a specific list of methods. In hop-server.xml, add a <allow-methods> element inside <authorization>:

<authorization>
  <users-file>config/hop-users.xml</users-file>
  <authentication-method>basic</authentication-method>
  <allow-methods>
    <method>Pipeline.run</method>
    <method>Pipeline.stop</method>
    <method>Pipeline.status</method>
    <method>Job.run</method>
    <method>Job.stop</method>
    <method>Job.status</method>
  </allow-methods>
</authorization>

This list permits only the six methods needed to run, stop, and check pipelines and jobs remotely. All other methods (e.g., getRootFolder, executeTransform) return a permission error. Customize the list based on your actual API usage. If you later need to add a method, append it to the list and restart the server.

After each configuration change, restart the Carte server and run a verification command. For example, after enabling authentication and restricting methods, test a valid authenticated call and an invalid one:

Valid call (should return XML status):

curl -u admin:YourStrongPassword! http://hop-server-01:8080/kettle/status

Invalid method call (should return an access denied error):

curl -u admin:YourStrongPassword! -d @/tmp/unauthorized-request.xml http://hop-server-01:8080/kettle/

Where /tmp/unauthorized-request.xml contains an XML-RPC request for Pipeline.pause (a method not in the allow list). The exact error format varies, but the HTTP status should be 403 or 500 with an XML fault. If the server returns 200, the method restriction is not active.

Prerequisites: write permission to the config directory, ability to restart the Carte server, and a valid backup of the original hop-server.xml.

Blast radius: each change affects only the Carte server. A misconfiguration can lock you out of the API, but local file access remains intact.

Verification: use curl to test unauthenticated and authenticated requests as shown. Check the server log (logs/hop-server.log) for authentication and authorization messages.

Recovery: if authentication breaks access unexpectedly, stop the server, restore the backup file (cp config/hop-server.xml.bak-20250321 config/hop-server.xml), and restart. If the allow-methods list blocks a needed method, edit the XML to add the method and restart.

Verification and Diagnostics

After each hardening step, you need to confirm that the intended security control is active and that legitimate operations still work. This section provides a systematic verification procedure.

1. Unauthenticated Access Test

Run the following curl command against your Carte server, expecting a 401 response:

curl -I http://hop-server-01:8080/kettle/status

Expected output:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="Hop"

If you see a 200, authentication is not enabled or not applied to this endpoint. Check that the hop-server.xml has the <authorization> element and that the server was restarted.

2. Authenticated Access Test

Use valid credentials to access the status endpoint:

curl -u admin:YourStrongPassword! -i http://hop-server-01:8080/kettle/status

Expected output: HTTP 200 and an XML or JSON payload containing server status information. If you get 401, the credentials are wrong or the user database is not being read. Verify with hop-encrypt.sh --list-users.

3. XML-RPC Method Restriction Test

Send a request for a method that is not in your allow list. For example, if Pipeline.pause is not allowed, construct a minimal XML-RPC request and post it:

curl -u admin:YourStrongPassword! -H "Content-Type: text/xml" --data '<?xml version="1.0"?><methodCall><methodName>Pipeline.pause</methodName><params></params></methodCall>' http://hop-server-01:8080/kettle/

Expected result: HTTP 403 or an XML fault with a message indicating the method is not permitted. If the server returns 200 and attempts to process the call, the allow-methods restriction is not working.

4. Log Inspection

Hop's server log is the authoritative record for authentication and authorization events. Tail the log while performing the above tests:

tail -f logs/hop-server.log

Look for lines like:

INFO  2025-03-21 14:35:12,123 - Authentication failed for user 'admin' from 192.168.1.50
INFO  2025-03-21 14:36:45,456 - Authorization denied for method 'Pipeline.pause' (user 'admin')

These messages confirm that the security controls are being enforced. The absence of such events when you expect failures means the configuration is not active.

5. Pipeline Execution Test

Security changes must not break legitimate data processing. Run a simple sample pipeline via the Carte API to ensure that an authorized user can execute allowed methods. If you have a pipeline file like samples/transformations/hello-world.hpl, submit it using the Hop command-line client or a direct XML-RPC call. A successful run should return a status of Finished and produce the expected output.

Diagnostic checklist:

• curl -I returns 401 for unauthenticated requests.
• curl -u returns 200 for authenticated requests.
• Forbidden method returns 403 or XML fault.
• Server log contains authentication/authorization entries.
• Sample pipeline runs without errors.

If any check fails, stop and revert the last change before proceeding.

Failure Modes and Recovery

Even with careful planning, hardening changes can fail. Knowing the common failure modes and their recovery steps reduces downtime and frustration.

Failure 1: Locked Out of the Carte Server

Symptoms: every request, including with known credentials, returns 401. Server log shows repeated authentication failures.

Possible causes: hop-users.xml corrupted or deleted; password changed outside the utility; authentication-method set incorrectly.

Recovery:

1. Stop the Carte server.
2. Restore the backup of hop-users.xml (if you have one) or recreate the user database using hop-encrypt.sh with the original username and a new password.
3. Restore hop-server.xml from backup if it was modified.
4. Start the server and test with curl -u.

If you do not have a backup of hop-users.xml, you can regenerate it from scratch, but you will need to reset passwords for all users.

Failure 2: Legitimate XML-RPC Method Blocked

Symptoms: a scheduled job or external system starts failing with XML-RPC errors indicating a method is not allowed. The server log shows "Authorization denied for method ...".

Cause: the method was not included in the <allow-methods> list, or the list was too restrictive.

Recovery:

1. Identify the blocked method from the log.
2. Edit hop-server.xml to add the method to <allow-methods>.
3. Restart the server.
4. Re-run the failing request to confirm it succeeds.

Failure 3: Server Does Not Start After Configuration Change

Symptoms: the Carte server fails during startup with a configuration error.

Cause: malformed XML in hop-server.xml (e.g., unclosed tag, incorrect element order).

Recovery:

1. Check the server log for the exact error line, often pointing to the line number in hop-server.xml.
2. If the error is not obvious, restore the backup of hop-server.xml.
3. Start the server and confirm it runs.
4. Re-apply the change carefully, using an XML validator if available.

Failure 4: Pipeline Execution Fails After Hardening

Symptoms: pipelines that worked before now fail with authorization or authentication errors.

Cause: the service account used by the pipeline does not have the required permissions, or the pipeline calls a method not in the allow list.

Recovery:

1. Check the pipeline logs and server log for the exact error.
2. If it is an authentication error, verify the credentials in the pipeline configuration.
3. If it is an authorization error, add the necessary method to the allow list or grant the user sufficient permissions (if using a more complex authorization model).
4. Test with a simple pipeline using the same credentials.

General Recovery Principles

• Always maintain a timestamped backup of hop-server.xml and hop-users.xml before making changes.
• Make one change at a time. If multiple changes fail, revert to the last known good state and re-apply changes one by one.
• Use a staging environment to test hardening steps before applying to production.
• Document each change with the date, rationale, and verification result.

Operations Checklist

Use this checklist to standardize Apache Hop security hardening across your team. Replace the example values with your own environment details.

Fill in the Owner column with responsible individual names and update Status as each item is completed. Use this checklist for every environment (development, staging, production). Keep the completed checklists as part of your audit trail.

Conclusion

Apache Hop security hardening is a continuous process, not a one-time script. Each recommendation in this article is version-scoped for Hop 1.2.x and 2.x, observable through commands and logs, and reversible when backups are maintained. The key discipline is to observe before changing, change one small piece, verify the expected outcome, and have a tested recovery path.

Start with the low-risk version and topology inventory. Then enable authentication on your Carte server using the built-in user database. Replace or remove default users. Restrict the XML-RPC API to only the methods your pipelines and jobs actually use. After each change, run the verification commands: unauthenticated requests should fail with 401, authenticated requests should succeed with 200, forbidden methods should return 403, and the server log should record security events. If anything behaves unexpectedly, stop and revert using your backups.

Finally, adopt the operations checklist for every environment and track completion. Assign owners, record dates, and keep the checklists as evidence of your hardening work. By following this controlled approach, you reduce the risk of a security breach and build confidence that your Apache Hop deployment remains secure as it evolves.

For further reading, review the official Apache Hop documentation on Carte server security and the hop-encrypt utility. Keep your Hop installation updated to the latest patch release, as security fixes are regularly included.