com.trendmicro.grid.acl.l0
Interface PublicFileService

All Superinterfaces:

Service

All Known Subinterfaces:

FileService

@PublicRequestContext
@WebServlet(value="/ws/level-0/files")
public interface PublicFileService
extends Service

Defines public reachable services to query file details.

Version:

1.0

Author:

Juergen_Kellerer, 2010-04-23

Method Summary

FileDetails	getFileDetails(FileIdentifier file) Returns the file details for the given file.
Collection<FileDetails>	getFileDetailsList(BatchCollection<FileIdentifier> files) Returns the file details list for the given files.
FileInformation	getFileInformation(FileIdentifier file) Returns the file information for the given file.
Collection<FileInformation>	getFileInformationList(BatchCollection<FileIdentifier> files) Returns the file information list for the given files.
FileIdentiferListPage	getFilesTaggedWith(String[] tags, int pageNumber) Returns all known files that are tagged with the given list of tags.
FileIdentiferListPage	getMatchingFiles(String tagExpression, String tagExpressionVersion, int pageNumber) Returns all known files that are matched by the given tag expression.
FileIdentiferListPage	getMatchingFilesInRange(String tagExpression, String tagExpressionVersion, Range range, int pageNumber) Returns all known files that are matched by the given tag expression and are in the given range.
boolean	isFileKnown(FileIdentifier file) Returns true if the GRID database knows (contains) the given file.
IsTrueResult	isFileKnownGood(FileIdentifier file) Returns 'Yes' if the GRID database knows that the file is good.
IsTrueResult	isFilePureWhite(FileIdentifier file) Returns 'Yes' if the GRID database knows that the file is good and not included in the high risk category.
Collection<Boolean>	isFilesKnown(BatchCollection<FileIdentifier> files) Implements a batch query for isFileKnown(FileIdentifier).
Collection<IsTrueResult>	isFilesKnownGood(BatchCollection<FileIdentifier> files) Implements a batch query for isFileKnownGood(FileIdentifier).
Collection<IsTrueResult>	isFilesPureWhite(BatchCollection<FileIdentifier> files) Implements a batch query for isFilePureWhite(FileIdentifier).
Collection<Boolean>	isFilesTaggedWith(BatchCollection<FileIdentifier> files, String[] tags) Deprecated. Please use isFilesTaggedWithAll(BatchCollection, String[]) instead.
Collection<IsTrueResult>	isFilesTaggedWithAll(BatchCollection<FileIdentifier> files, String[] tags) Returns 'Yes' if the given files are tagged with the specified tags.
Boolean	isFileTaggedWith(FileIdentifier file, String[] tags) Deprecated. Please use isFileTaggedWithAll(FileIdentifier, String[]) instead.
IsTrueResult	isFileTaggedWithAll(FileIdentifier file, String[] tags) Returns 'Yes' if the given file is tagged with the specified tags.

Method Detail

isFileKnown

@RequiredRoles(value="run.hash.queries")
boolean isFileKnown(FileIdentifier file)
                    throws AuthenticationException

Returns true if the GRID database knows (contains) the given file.

Note: Calling this method doesn't make a guarantee whether the file content is stored inside the GRID, it only checks whether the database knows details on the file.

Parameters:

file - the file to check.

Returns:

true if the GRID database contains the file and the file is not labelled as 'unknown', false otherwise.

Throws:

AuthenticationException - In case of this service requires authentication and the current user session is not authenticated or doesn't have the right to access the service.

isFilesKnown

@RequiredRoles(value="run.hash.queries")
Collection<Boolean> isFilesKnown(BatchCollection<FileIdentifier> files)
                                 throws AuthenticationException

Implements a batch query for isFileKnown(FileIdentifier).

Parameters:

files - the files to check.

Returns:

a collection that contains the results of the requested files.

Throws:

AuthenticationException - In case of this service requires authentication and the current user session is not authenticated or doesn't have the right to access the service.

isFileKnownGood

@RequiredRoles(value="run.hash.queries")
IsTrueResult isFileKnownGood(FileIdentifier file)
                             throws AuthenticationException

Returns 'Yes' if the GRID database knows that the file is good.

Parameters:

file - the file to check.

Returns:

'Yes' if the GRID database contains the file and the file is tagged as 'clean', 'No' if the file is not 'clean', 'NotKnown' if the file is not contained in the GRID database.

Throws:

AuthenticationException - In case of this service requires authentication and the current user session is not authenticated or doesn't have the right to access the service.

isFilesKnownGood

@RequiredRoles(value="run.hash.queries")
Collection<IsTrueResult> isFilesKnownGood(BatchCollection<FileIdentifier> files)
                                          throws AuthenticationException

Implements a batch query for isFileKnownGood(FileIdentifier).

Parameters:

files - the files to check.

Returns:

a collection that contains the results of the requested files.

Throws:

AuthenticationException - In case of this service requires authentication and the current user session is not authenticated or doesn't have the right to access the service.

isFilePureWhite

@RequiredRoles(value="run.hash.queries")
IsTrueResult isFilePureWhite(FileIdentifier file)
                             throws AuthenticationException

Returns 'Yes' if the GRID database knows that the file is good and not included in the high risk category.

Parameters:

file - the file to check.

Returns:

'Yes' if the GRID database contains the file and the file is tagged as 'clean' and not 'key_loggers' and not 'password_crackers' and not 'proxy_anonymizers', 'No' if the file is not 'clean' or 'key_loggers' or 'password_crackers' or 'proxy_anonymizers', 'NotKnown' if the file is not contained in the GRID database.

Throws:

AuthenticationException - In case of this service requires authentication and the current user session is not authenticated or doesn't have the right to access the service.

isFilesPureWhite

@RequiredRoles(value="run.hash.queries")
Collection<IsTrueResult> isFilesPureWhite(BatchCollection<FileIdentifier> files)
                                          throws AuthenticationException

Implements a batch query for isFilePureWhite(FileIdentifier).

Parameters:

files - the files to check.

Returns:

a collection that contains the results of the requested files.

Throws:

AuthenticationException - In case of this service requires authentication and the current user session is not authenticated or doesn't have the right to access the service.

isFileTaggedWith

@Deprecated
@RequiredRoles(value="run.hash.queries")
Boolean isFileTaggedWith(FileIdentifier file,
                                                       String[] tags)
                         throws AuthenticationException

Deprecated. Please use isFileTaggedWithAll(FileIdentifier, String[]) instead.

Returns true if the given file is tagged with the specified tags.

Example: Check whether a file is known and good:

 FileIdentifier id = new FileIdentifier(sha1Hash);
 Boolean isClean = publicFileService.isFileTaggedWith(id, "clean");
 if (isClean == null) {
    // file is unknown
 } else if (isClean) {
    // file is known bood
 } else {
    // file is known bad
 }
 

Parameters:

file - The file to verify.

tags - The tags to check against.

Returns:

True if the tags apply to the file, false if not, 'null' if the file is unknown.

Throws:

AuthenticationException - In case of this service requires authentication and the current user session is not authenticated or doesn't have the right to access the service.

isFilesTaggedWith

@Deprecated
@RequiredRoles(value="run.hash.queries")
Collection<Boolean> isFilesTaggedWith(BatchCollection<FileIdentifier> files,
                                                                    String[] tags)
                                      throws AuthenticationException

Deprecated. Please use isFilesTaggedWithAll(BatchCollection, String[]) instead.

Returns true if the given files are tagged with the specified tags.

Implements a batch query for isFileTaggedWith(FileIdentifier, String[]).

Important Note: This method returned incorrect data when 'null' values were contained in the result. 'Null' values are swallowed by the XML serialization framework, because it considers the booleans as primitive types. Therefore starting from GACL 1.2, this method substitutes 'null' with 'false'. Use isFilesTaggedWithAll(BatchCollection, String[]) instead, to get a 3-way result.

Parameters:

files - The files to verify.

tags - The tags to check against.

Returns:

True if the tags apply to the files, false if not.

Throws:

AuthenticationException - In case of this service requires authentication and the current user session is not authenticated or doesn't have the right to access the service.

isFileTaggedWithAll

@RequiredRoles(value="run.hash.queries")
IsTrueResult isFileTaggedWithAll(FileIdentifier file,
                                                    String[] tags)
                                 throws AuthenticationException

Returns 'Yes' if the given file is tagged with the specified tags.

Example: Check whether a file is known and good:

 FileIdentifier id = new FileIdentifier(sha1Hash);
 switch(publicFileService.isFileTaggedWithAll(id, "clean")) {
    case Yes:        // file is known good
       break;
    case No:         // file is known bad
       break;
    case NotKnown:   // file is unknown
       break;
 }
 

When querying multiple files, isFilesTaggedWithAll(BatchCollection, String[]), may be more efficient.

Note: This method is a replacement for isFileTaggedWith(FileIdentifier, String[]) as a 3-way boolean is not obvious and not supported in all programming languages.

Parameters:

file - The file to verify.

tags - The tags to check against.

Returns:

True if the tags apply to the file, false if not, 'null' if the file is unknown.

Throws:

AuthenticationException - In case of this service requires authentication and the current user session is not authenticated or doesn't have the right to access the service.

isFilesTaggedWithAll

@RequiredRoles(value="run.hash.queries")
Collection<IsTrueResult> isFilesTaggedWithAll(BatchCollection<FileIdentifier> files,
                                                                 String[] tags)
                                              throws AuthenticationException

Returns 'Yes' if the given files are tagged with the specified tags.

Implements a batch query for isFileTaggedWithAll(FileIdentifier, String[]).

Note: This method is a replacement for isFilesTaggedWith(BatchCollection, String[]) as a 3-way boolean is not obvious and not supported in all programming languages.

Parameters:

files - The files to verify.

tags - The tags to check against.

Returns:

a collection that contains the results of the requested files.

Throws:

AuthenticationException - In case of this service requires authentication and the current user session is not authenticated or doesn't have the right to access the service.

getFilesTaggedWith

@RequiredRoles(value="run.tag.matching.queries")
FileIdentiferListPage getFilesTaggedWith(String[] tags,
                                                            int pageNumber)
                                         throws AuthenticationException

Returns all known files that are tagged with the given list of tags.

Parameters:

tags - The tags to get the files for.

pageNumber - The number of the list page to return, starting from 0 for the first chunk.

Returns:

A chunk of file identifiers for the files tagged with the given tags or 'null' if no chunk exists under the given number.

Throws:

AuthenticationException - In case of this service requires authentication and the current user session is not authenticated or doesn't have the right to access the service.

getMatchingFiles

@RequiredRoles(value="run.tag.matching.queries")
FileIdentiferListPage getMatchingFiles(String tagExpression,
                                                          String tagExpressionVersion,
                                                          int pageNumber)
                                       throws AuthenticationException

Returns all known files that are matched by the given tag expression.

Tag Query Grammar
A common tag query uses a simple search grammar also common for most search engines:

• Tags are delimited by whitespaces
• Adding "-" in front of a tag negates the search (the tag must not be included in results)
• Groups can be built by adding braces around tags. Multiple groups are combined with OR (the same as if multiple individual queries would be combined).
• Tags in one group are combined with AND (all have to be included (or excluded when prefixed with "-"))

The example query: (mustBeInGroup1 -mustNotBeInGroup1) (mustBeInGroup2 -mustNotBeInGroup2 mustBe2InGroup2) selects all files that were tagged with "mustBeInGroup1" but not with "mustNotBeInGroup1" and files that were tagged with "mustBeInGroup2" and "mustBe2InGroup2" but not "mustNotBeInGroup2".

Parameters:

tagExpression - An expression following the tag query grammar used to identify files.

tagExpressionVersion - The version of the expression (the most recent version is assumed if omitted).

pageNumber - The number of the list page to return, starting from 0 for the first chunk.

Returns:

A chunk of file identifiers for the files, matching the given expression or 'null' if no chunk exists under the given number.

Throws:

AuthenticationException - In case of this service requires authentication and the current user session is not authenticated or doesn't have the right to access the service.

getMatchingFilesInRange

@RequiredRoles(value="run.tag.matching.queries")
FileIdentiferListPage getMatchingFilesInRange(String tagExpression,
                                                                 String tagExpressionVersion,
                                                                 Range range,
                                                                 int pageNumber)
                                              throws AuthenticationException

Returns all known files that are matched by the given tag expression and are in the given range.

Parameters:

tagExpression - An expression following the tag query grammar used to identify files.

tagExpressionVersion - The version of the expression (the most recent version is assumed if omitted).

range - The range limiting the output.

pageNumber - The number of the list page to return, starting from 0 for the first chunk.

Returns:

A chunk of file identifiers for the files, matching the given expression or 'null' if no chunk exists under the given number.

Throws:

AuthenticationException - In case of this service requires authentication and the current user session is not authenticated or doesn't have the right to access the service.

getFileInformation

@RequiredRoles(value="run.hash.queries")
FileInformation getFileInformation(FileIdentifier file)
                                   throws AuthenticationException

Returns the file information for the given file.

Parameters:

file - The file to return the information for.

Returns:

the file information for the given file or 'null' if the file is unknown.

Throws:

AuthenticationException - In case of this service requires authentication and the current user session is not authenticated or doesn't have the right to access the service.

getFileInformationList

@ResponseWrapper(className="com.trendmicro.grid.acl.l0.wrappers.GetFileInformationListResponse")
@RequiredRoles(value="run.hash.queries")
Collection<FileInformation> getFileInformationList(BatchCollection<FileIdentifier> files)
                                                   throws AuthenticationException

Returns the file information list for the given files.

Parameters:

files - The files to return the information list for.

Returns:

the file information list for the given file. The list may contain 'null' entries if the corresponding file was unknown.

Throws:

AuthenticationException - In case of this service requires authentication and the current user session is not authenticated or doesn't have the right to access the service.

getFileDetails

@RequiredRoles(value={"run.hash.queries","access.details"})
FileDetails getFileDetails(FileIdentifier file)
                           throws AuthenticationException

Returns the file details for the given file.

Parameters:

file - The file to return the details for.

Returns:

the file details for the given file or 'null' if the file is unknown.

Throws:

AuthenticationException - In case of this service requires authentication and the current user session is not authenticated or doesn't have the right to access the service.

getFileDetailsList

@ResponseWrapper(className="com.trendmicro.grid.acl.l0.wrappers.GetFileDetailsListResponse")
@RequiredRoles(value={"run.hash.queries","access.details"})
Collection<FileDetails> getFileDetailsList(BatchCollection<FileIdentifier> files)
                                           throws AuthenticationException

Returns the file details list for the given files.

Parameters:

files - The files to return the details list for.

Returns:

the file details list for the given file. The list may contain 'null' entries if the corresponding file was unknown.

Throws:

AuthenticationException - In case of this service requires authentication and the current user session is not authenticated or doesn't have the right to access the service.