Skip to main content

SSH Connection

Automate the fulfillment of data subject access, deletion, opt-out, and identifier retrieval requests using a command line argument on a remote server.

Response Format​

Results should be reported via stdout as an array of objects. Each object in the array will result in a separate file for you data subject. Below are examples of properly formatted responses:

Example Access Response
[
  {
    "first_name": "Howard",
    "last_name": "Spears",
    "address1": {
      "street": "123 Any Street",
      "city": "San Francisco",
      "state": "California",
      "zip_code": "92123"
    }
  },
  {
    "first_name": "Susan",
    "last_name": "Spears",
    "address1": {
      "street": "123 Any Street",
      "city": "San Francisco",
      "state": "California",
      "zip_code": "92123"
    }
  }
]
Example Deletion Response
[
  {
    "status": "success"
  }
]
Debugging Malformed Requests

The environment variable LOGLEVEL can be adjusted to DEBUG to get more detailed feedback if responses are malformed.

Be aware that this level of logging has the potential to expose sensitive data!

Setup Instructions​

In the setup process below, you will create and configure a Connection object with a SSH ConnectorType that is used to instantiate a connection. The agent configuration will be updated by placing the connection object into the DataGrailAgentConfig connections array.

Example Connection Object
{
  "name": "DSR Script",
  "uuid": "7cf6642d-da70-401b-af14-a02c0e13e5f6",
  "capabilities": ["privacy/access", "privacy/deletion", "privacy/optout", "privacy/identifiers"],
  "mode": "live",
  "connector_type": "SSH",
  "queries": {
    "access": ["./dsr.py access {email}"],
    "delete": ["./dsr.py delete {email}"],
    "optout": ["./dsr.py optout {email}"],
    "identifiers": {
      "phone_number": ["./dsr.py identifiers {email}"]
    }
  },
  "credentials_location": "arn:aws:secretsmanager:Region:AccountId:secret:datagrail-rm-agent-ssh"
}
Prerequisites

Before performing the steps below, ensure the following:

  • Request Manager Agent is deployed and connected in DataGrail.
  • Network is configured to allow the Agent to connect with the SSH instance.

Create and Store Credentials​

  1. In SSH, create a new user for the agent. Only grant the minimum necessary permissions for executing the request.

  2. Create a new user for the agent, using either password or private key authentication (recommended).

  3. Configure the following JSON key-value pairs:

    {
      "username": "<agent user>",
      "password": "(optional) <agent password>",
      "private_key": "(preferred over password) <PEM encoded private key>",
      "server": "<hostname or IP Address of server>",
      "port": "(optional) <port to connect to, defaults to 22>"
    }

  4. Store the JSON value in your vault with an entry name like datagrail-rm-agent-ssh.

  5. Ensure that the agent is configured to retrieve the value of this vault entry.

Create Connection Object​

To define the interactions between the agent and the internal system, configure the Connection object.

  1. Using the empty connection object below, enter a connection name and uuid (v4).

    {
      "name": "",
      "uuid": "",
      "capabilities": [],
      "mode": "",
      "connector_type": "SSH",
      "queries": {
        "access": [],
        "delete": [],
        "optout": [],
        "identifiers": {}
      },
      "credentials_location": ""
    }

  2. Set the capabilities that correspond to your request logic.

  3. Under queries, add your request logic as a string to the corresponding request type.

  4. The queries object allows query strings to be dynamically formatted with identifiers. Identifiers are passed individually to queries, and are bound to the variables in the operation. Replace any static identifier in the request logic using curly braces to wrap the identifier, which will be run through shlex.quote (e.g., ...--email={email}).

    Parameter Binding Example
    # BEFORE
    ./dsr.py access 'subject@domain.com'

    # AFTER
    ./dsr.py access {email}

  5. Set the credentials_location value to the location of the secret created above (e.g., AWS ARN).

Example Connection Objects

After following the steps above, the resulting connection object should look similar to these examples.

Example Connection Object with Access Capability
{
  "name": "DSR Script",
  "uuid": "7cf6642d-da70-401b-af14-a02c0e13e5f6",
  "capabilities": ["privacy/access"],
  "mode": "live",
  "connector_type": "SSH",
  "queries": {
    "access": ["./dsr.py access {email}"],
    "delete": [],
    "optout": [],
    "identifiers": {}
  },
  "credentials_location": "arn:aws:secretsmanager:Region:AccountId:secret:datagrail-rm-agent-ssh"
}

Update and Restart Agent​

In this section, you will integrate the internal system with DataGrail by updating the agent environment variable and restarting the agent to apply the changes.

Already Processing Requests?

If your DataGrail account is already processing Data Subject Requests, new agent connections may be automatically processed with all new requests. If you are not sure, check with your DataGrail admin or dedicated Account Manager before starting this section.

  1. In the DATAGRAIL_AGENT_CONFIG environment variable, add the new connection object to the connections array.
  2. Save the environment variable, and restart the agent service to apply the changes.
  3. After the restart, confirm that the agent service is healthy, and the logs contain no errors.
  4. In DataGrail, update the integration by navigating to Integrations and select the agent integration.
  5. Select Edit Integration, enter the Client Secret, and then select Save Changes.
  6. To view the new connection, navigate back to Integrations and locate it in the list.
Processing Your First Request

Now that you've successfully added this connection to DataGrail, try it out by submitting and processing a request.

 

Need help?
If you have any questions, please reach out to your dedicated Account Manager or contact us at support@datagrail.io.

Disclaimer: The information contained in this message does not constitute as legal advice. We would advise seeking professional counsel before acting on or interpreting any material.