Server to agent response JSON - Gargravarr2112/vFense GitHub Wiki

(Under discussion/development. Things may change from what has been specified.)

Agent operations

The only way the server can get the agent to do something is through "operations." We have agreed upon a format for the JSON that the server responds with when the agent does its check-in or when the server has a response from an API call.

Server response message JSON format:

{
    "count": 1,                 # Check server documentation for more information
    "vfense_status_code": 1001, # Check server documentation for more information
    "uri": "what uri this message is returning from",
    "http_method": "GET"/"PUT"/"POST", 
    "http_status": 200/500/404/405/..., 
    "message": "Any message the server would like to tell the agent",
    "operations": [
        {
            "operation": "the type of operation",         # Must be a string
            "data": {data for this operation goes here},  # Can be any data type depending on the operation
            ... any extra keys depending on the operation
        },
        ... all other operations, if any
    ]
}

In this section we are more concerned about the "operations" key.

The "operations" key must have a list as its value as this is what the agent iterates over to create operations. Each element of this list must be a dictionary containing at a minimum the "operation" and "data" keys. The "operation" key specifies what type of operation it is, and the "data" key has all relevant information for that operation. The agent parses the "data" key depending on predefined formats which have been agreed upon for each operation, which are then coded into the agent.

Here is an example of the "refresh_response_uris" operation. The agent calls upon the "refresh_response_uris" API using the "rvl/v2/core/uris/response" URI, and the server responds with:

{
    "count": 1, 
    "vfense_status_code": 1001, 
    "uri": "/rvl/v2/core/uris/response", 
    "http_method": "GET", 
    "http_status": 200, 
    "message": "response uris retrieved successfully.",
    "operations": [
        {
            "operation": "refresh_response_uris",
            "data": {
                "refresh_apps": {
                    "response_uri": "rvl/v2/{0}/apps/results/refresh_apps", 
                    "request_method": "PUT", 
                }, 
                "reboot": {
                    "response_uri": "rvl/v2/{0}/core/results/reboot", 
                    "request_method": "PUT", 
                }, 
                "check_in": {
                    "response_uri": "rvl/v2/{0}/core/checkin", 
                    "request_method": "GET", 
                }, 
                "uninstall_agent": {
                    "response_uri": "rvl/v2/{0}/apps/results/uninstall", 
                    "request_method": "PUT", 
                }, 
                "validate_token": {
                    "response_uri": "rvl/v2/core/validate_token", 
                    "request_method": "GET", 
                }, 
                "available_agent_update": {
                    "response_uri": "rvl/v2/apps/available_agent_update", 
                    "request_method": "PUT", 
                }, 
                "startup": {
                    "response_uri": "rvl/v2/{0}/core/startup", 
                    "request_method": "PUT", 
                }, 
                "install_os_apps": {
                    "response_uri": "rvl/v2/{0}/apps/results/install/os", 
                    "request_method": "PUT", 
                }, 
                "install_supported_apps": {
                    "response_uri": "rvl/v2/{0}/apps/results/install/supported", 
                    "request_method": "PUT", 
                }, 
                "refresh_response_uris": {
                    "response_uri": "rvl/v2/core/uris/response", 
                    "request_method": "GET", 
                }, 
                "install_agent_update": {
                    "response_uri": "rvl/v2/{0}/apps/results/install/agent", 
                    "request_method": "PUT", 
                }, 
                "shutdown": {
                    "response_uri": "rvl/v2/{0}/core/results/shutdown", 
                    "request_method": "PUT", 
                }, 
                "new_token": {
                    "response_uri": "rvl/v2/{0}/core/results/newtoken", 
                    "request_method": "PUT", 
                }, 
                "install_custom_apps": {
                    "response_uri": "rvl/v2/{0}/apps/results/install/custom", 
                    "request_method": "PUT", 
                }, 
                "monitor_data": {
                    "response_uri": "rvl/v2/{0}/monitoring/monitordata", 
                    "request_method": "POST", 
                }, 
                "uninstall": {
                    "response_uri": "rvl/v2/{0}/apps/results/uninstall", 
                    "request_method": "PUT", 
                }
            }
        }
    ]
}

As you can see, for the "refresh_response_uris" operation, the "data" key contains a dictionary, but it can be anything depending on the operation and what has been previously agreed upon.