File Catalog Api Get File Catalog Entry

File Catalog Api Get File Catalog Entry
Get a file catalog entry

Returns the entry with the hypervisors that have the file. Accessible to every authenticated role.

Request
URI
GET
https://{api_host}/api/v1/file-catalog/{fileId}
COPY
Path Parameters
integer
fileId
Required  

File catalog entry id

fileId example
101

Authentication
This operation uses the following authentication methods.
Responses
200

200 OK successful response envelope. The entry with the hypervisors that have the file

Returns FileCatalogDetailDto of type(s) application/json
{
    "fileId": 101,
    "fileName": "backup-agent.sh",
    "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "fileKind": "SCRIPT",
    "globalState": "UNAPPROVED",
    "hypervisorCount": 2,
    "fileSize": 2048,
    "instances": [
        {
            "endpointId": "2",
            "hostname": "esx02.example.com",
            "path": "/opt/backup/backup-agent.sh"
        },
        {
            "endpointId": "4",
            "hostname": "esx04.example.com",
            "path": "/opt/backup/backup-agent.sh"
        }
    ]
}
integer As int64 As int64
fileId
Required  

Identifier of the catalog entry; there is one entry per distinct SHA-256, created when an agent first reports the hash

string
fileName
Required  

Last path segment of the path under which an agent first reported the hash, cut to 255 characters. Later reports of the same hash under another name do not change it

string As ^[a-f0-9]{64}$
sha256
Required  

64 lowercase hex characters

string
fileKind
Optional

Kind of file as classified by the agent.

  • ELF: The agent classified the file by its ELF header (0x7f followed by ELF)
  • SCRIPT: The agent classified the file by a leading #! line
  • EXECUTABLE_OTHER: The agent qualified the file only by its executable permission
Enumeration: ELF, SCRIPT, EXECUTABLE_OTHER
string
publisher
Optional

Absent until the agent reports a publisher or signer

string
globalState
Required  

Global file catalog state. It follows the action of the mapped rule: no rule or AUDIT is UNAPPROVED, ALLOW is APPROVED, BLOCK is BANNED.

  • UNAPPROVED: The entry has no rule or its rule's action is AUDIT; the state of a new entry
  • APPROVED: The entry's rule has the action ALLOW
  • BANNED: The entry's rule has the action BLOCK
Enumeration: UNAPPROVED, APPROVED, BANNED
integer As int64 As int64
hypervisorCount
Required  

Number of distinct hypervisors that currently have the file

object
rule
Optional

The catalog rule of an entry.

integer As int64 As int64
fileSize
Optional

File size in bytes as first reported by an agent. Omitted when the agent reported none

array of object
instances
Required  
Constraints: maxItems: 1000

At most 1,000 instances, ordered by hostname then path


400

400 Bad Request: INVALID_ARGUMENT when the fileId path variable is not a number

Returns ApiErrorResponse of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


401

401 Unauthorized: UNAUTHENTICATED when the VTP_SESSION cookie is missing, unknown, expired or revoked

Returns Unauthenticated of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


404

404 Not Found: FILE_NOT_FOUND

Returns ApiErrorResponse of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


Code Samples
COPY
                    curl -H 'Authorization: <value>' https://{api_host}/api/v1/file-catalog/{fileId}