WSDL

All hash related service methods are defined within the WSDL url:
https://mygacl.trendmicro.com/ws/level-0/files?wsdl and (non-public) https://mygacl.trendmicro.com/ws/level-0/internal/files?wsdl

The FileIdentifier

As a general rule of thumb, all hash based SOAP queries require at least one FileIdentifier as input parameter. Methods that require more than one identifier, return a list of results instead of a single result. If multiple results are returned, the first result corresponds to the first input identifier, the second to the second and so forth.

A FileIdentifier has 2 properties, a SHA1 and an optional MD5 hash identifying the file. MD5 is not required, though if specified both hashes are compared for maximum security (not needed in the majority of cases).

Depending on the way the SOAP stubs were created, the file identifier expects the hashes in their byte[] or hex encoded string representation (the latter is also the format used within XML).

Java Example:

 // 20 byte SHA1 hash...
byte[] sha1 = new BigInteger("289959da899bf03a34dd232ac70205df401098b0", 16).toByteArray();
FileIdentifier fid = new FileIdentifier();
fid.setSha1(sha1);

C# Example:

// 40 chars hex encoded SHA1 hash...
string sha1 = "289959da899bf03a34dd232ac70205df401098b0";
fileIdentifier fid = new fileIdentifier();
fid.sha1 = sha1;

PHP Example:

// 40 chars hex encoded SHA1 hash...
$sha1 = "289959da899bf03a34dd232ac70205df401098b0";
array("file", array("sha1" => $sha1));
// Note: In PHP the name of the identifier depends on the name of the
// input parameter ("file") of the service method. If the input parameter
// is a list, use array(array("sha1" => $sha1), ...).

Primary SOAP Interfaces

• isFileKnown(FileIdentifier) and isFilesKnown(FileIdentifier[])
  • Returns true or false depending on whether the GRID knows or does not know the file or files.
  • Returns a list of true or false if isFiles... was issued.
• isFileKnownGood(FileIdentifier) and isFilesKnownGood(FileIdentifier[])
  • Returns Yes / No / NotKnown depending on whether the file is considered GOOD, BAD or the answer is unknown as the file doesn't exist in the GRID database.
  • Returns a list of Yes / No / NotKnown if isFiles... was issued.
  • Is a shortcut to using one of the methods "...TaggedWithAll(..., "clean")".
• isFileTaggedWithAll(FileIdentifier id, String[] tags) and isFilesTaggedWithAll(FileIdentifier[] ids, String[] tags)
  • Returns Yes / No / NotKnown depending on whether the file is tagged with all the given tags, not tagged with all given tags or the answer is unknown as the file doesn't exist in the GRID database.
  • Returns a list of Yes / No / NotKnown if isFiles... was issued.
  • Requires the knowledge of available tags (see getFileInformation).

Additional SOAP Interfaces

Provide access to metadata or tag related file information using a known hash as query parameter. The returned information can be seen within the class diagrams.

• getFileInformation(FileIdentifier) and getFileInformationList(FileIdentifier[])
  • Returns the type FileInformation or 'null' depending on whether the file exists within the GRID or not.
  • FileInformation can be used see:
    • All tags that apply to a file
    • Verify when it was first added and last processed.
    • Check the popularity via sourcePackageCount (= number of known software packages containing this file) and sourceSiteCount (= number of public sites offering the file directly).
• getFileDetails(FileIdentifier) and getFileDetailsList(FileIdentifier[])
  • Returns the type FileDetails or 'null' depending on whether the file exists within the GRID or not.
  • FileDetails can be used to see all metadata that apply to a file (this may include a subset of the file properties and additional static analysis offered by the GRID).
  • The amount of visible metadata differs depending on whether the public or "/internal/" file service is used.
  • FileInformation is always included in the details type (there's no need for a separate query).