Download

Download a file from the target to the Apfell server

What does it mean to download a file?

This section is specifically for downloading a file from the agent to the Apfell server. Because these can be very large files that you task to download, a bit of processing needs to happen: the file needs to be chunked and routed through the agents.

In general, there's a few steps that happen for this process:

1. The operator issues a task to download a file, such as download file.txt

2. This gets sent down to the agent in tasking, the agent locates the file, and determines it has the ability to read it. Now it needs to send the data back

3. The agent first gets the full path of the file so that it can return that data. That's a quality of live requirement so that operators don't need to supply the full path when specifying files, but so that Apfell can still properly track all files, especially ones that have the same name.

4. The agent then sends an initial message to the Apfell server indicating that it has a file to send. The agent specifies how many chunks it'll take, and which task this is for.

5. The Apfell server then registers that file in the database so it can be tracked. This results in a file UUID. The Apfell server sends back this UUID so that the agent and Apfell can make sure they're talking about the same file for the actual transfer.

6. The agent then starts chunking up the data and sending it chunk by chunk. Each message will have chunk_size amount of data base64 encoded, the file UUID from step 5, and which chunk number is being sent.

7. The Apfell server responds back with a successful acknowledgement that it received each chunk

It's not an extremely complex process, but it does require a bit more back-and-forth than a fire-and-forget style. This process allows Apfell to track how many chunks it'll take to download a file and how many have been downloaded so far. The rest of this page will walk through those steps with more concrete code examples.

Example (agent response pt. 1):

When an agent is ready to transfer a file from agent to Apfell, it first needs to get the full_path of the file and determine how many chunks it'll take to transfer the file. It then creates the following structure:

{
    "total_chunks": 4, 
    "task_id": "UUID here",
    "full_path": "/test/test2/test3.file" // full path to the file downloaded
}

This message is what's sent as an Action: post_response message.

Apfell will respond with a file_id:

{
    "status": "success",
    "file_id": "UUID Here"
    "task_id": "task uuid here"
}

Example (agent response pt. 2-n):

The agent sends back each chunk sequentially and calls out the file_id its referring to along with the actual chunked data. The size of the chunks isn't tracked by Apfell right now, so make sure to send them in order.

{
    "chunk_num": 1, 
    "file_id": "UUID From previous response", 
    "chunk_data": "base64_blob==",
    "task_id": "task uuid"
}

For each chunk, Apfell will respond with a success message if all went well:

{
    "status": "success"
    "task_id": "task uuid here"
}

Once all of the chunks have arrived, the file will be downloadable from the Apfell server.