1 package com.trendmicro.grid.acl.l0; 2 3 import com.trendmicro.grid.acl.PublicRequestContext; 4 import com.trendmicro.grid.acl.RequiredRoles; 5 import com.trendmicro.grid.acl.Service; 6 import com.trendmicro.grid.acl.l0.datatypes.*; 7 8 import javax.jws.WebMethod; 9 import javax.jws.WebParam; 10 import javax.jws.WebResult; 11 import javax.jws.WebService; 12 import javax.servlet.annotation.WebServlet; 13 import javax.xml.ws.ResponseWrapper; 14 import java.util.Collection; 15 16 import static com.trendmicro.grid.acl.l0.KnownRoles.*; 17 18 /** 19 * Defines public reachable services to query file details. 20 * 21 * @author Juergen_Kellerer, 2010-04-23 22 * @version 1.0 23 */ 24 @PublicRequestContext 25 @WebServlet("/ws/level-0/files") 26 @WebService(targetNamespace = Level0Constants.NAMESPACE) 27 public interface PublicFileService extends Service { 28 29 /** 30 * Returns true if the GRID database knows (contains) the given file. 31 * <p/> 32 * Note: Calling this method doesn't make a guarantee whether the file content is stored 33 * inside the GRID, it only checks whether the database knows details on the file. 34 * 35 * @param file the file to check. 36 * @return true if the GRID database contains the file and the file is not labelled as 'unknown', 37 * false otherwise. 38 * @throws AuthenticationException In case of this service requires authentication and the current user session 39 * is not authenticated or doesn't have the right to access the service. 40 */ 41 @WebMethod 42 @WebResult(name = "fileKnown") 43 @RequiredRoles(ROLE_RUN_HASH_QUERIES) 44 boolean isFileKnown( 45 @WebParam(name = "file") FileIdentifier file) throws AuthenticationException; 46 47 /** 48 * Implements a batch query for {@link #isFileKnown(FileIdentifier)}. 49 * 50 * @param files the files to check. 51 * @return a collection that contains the results of the requested files. 52 * @throws AuthenticationException In case of this service requires authentication and the current user session 53 * is not authenticated or doesn't have the right to access the service. 54 */ 55 @WebMethod 56 @WebResult(name = "fileKnown") 57 @RequiredRoles(ROLE_RUN_HASH_QUERIES) 58 Collection<Boolean> isFilesKnown( 59 @WebParam(name = "file") BatchCollection<FileIdentifier> files) throws AuthenticationException; 60 61 /** 62 * Returns 'Yes' if the GRID database knows that the file is good. 63 * 64 * @param file the file to check. 65 * @return 'Yes' if the GRID database contains the file and the file is tagged as 'clean', 66 * 'No' if the file is not 'clean', 'NotKnown' if the file is not contained in the GRID database. 67 * @throws AuthenticationException In case of this service requires authentication and the current user session 68 * is not authenticated or doesn't have the right to access the service. 69 */ 70 @WebMethod 71 @WebResult(name = "fileKnownGood") 72 @RequiredRoles(ROLE_RUN_HASH_QUERIES) 73 IsTrueResult isFileKnownGood( 74 @WebParam(name = "file") FileIdentifier file) throws AuthenticationException; 75 76 /** 77 * Implements a batch query for {@link #isFileKnownGood(FileIdentifier)}. 78 * 79 * @param files the files to check. 80 * @return a collection that contains the results of the requested files. 81 * @throws AuthenticationException In case of this service requires authentication and the current user session 82 * is not authenticated or doesn't have the right to access the service. 83 */ 84 @WebMethod 85 @WebResult(name = "fileKnownGood") 86 @RequiredRoles(ROLE_RUN_HASH_QUERIES) 87 Collection<IsTrueResult> isFilesKnownGood( 88 @WebParam(name = "file") BatchCollection<FileIdentifier> files) throws AuthenticationException; 89 90 /** 91 * Returns 'Yes' if the GRID database knows that the file is good and not included in the high risk category. 92 * 93 * @param file the file to check. 94 * @return 'Yes' if the GRID database contains the file and the file is tagged as 'clean' and not 'key_loggers' 95 * and not 'password_crackers' and not 'proxy_anonymizers', 96 * 'No' if the file is not 'clean' or 'key_loggers' or 'password_crackers' or 'proxy_anonymizers', 97 * 'NotKnown' if the file is not contained in the GRID database. 98 * @throws AuthenticationException In case of this service requires authentication and the current user session 99 * is not authenticated or doesn't have the right to access the service. 100 */ 101 @WebMethod 102 @WebResult(name = "filePureWhite") 103 @RequiredRoles(ROLE_RUN_HASH_QUERIES) 104 IsTrueResult isFilePureWhite( 105 @WebParam(name = "file") FileIdentifier file) throws AuthenticationException; 106 107 /** 108 * Implements a batch query for {@link #isFilePureWhite(FileIdentifier)}. 109 * 110 * @param files the files to check. 111 * @return a collection that contains the results of the requested files. 112 * @throws AuthenticationException In case of this service requires authentication and the current user session 113 * is not authenticated or doesn't have the right to access the service. 114 */ 115 @WebMethod 116 @WebResult(name = "filePureWhite") 117 @RequiredRoles(ROLE_RUN_HASH_QUERIES) 118 Collection<IsTrueResult> isFilesPureWhite( 119 @WebParam(name = "file") BatchCollection<FileIdentifier> files) throws AuthenticationException; 120 121 /** 122 * Returns true if the given file is tagged with the specified tags. 123 * <p/> 124 * Example: Check whether a file is known and good:<code><pre> 125 * FileIdentifier id = new FileIdentifier(sha1Hash); 126 * Boolean isClean = publicFileService.isFileTaggedWith(id, "clean"); 127 * if (isClean == null) { 128 * // file is unknown 129 * } else if (isClean) { 130 * // file is known bood 131 * } else { 132 * // file is known bad 133 * } 134 * </pre></code> 135 * 136 * @param file The file to verify. 137 * @param tags The tags to check against. 138 * @return True if the tags apply to the file, false if not, 'null' if the file is unknown. 139 * @throws AuthenticationException In case of this service requires authentication and the current user session 140 * is not authenticated or doesn't have the right to access the service. 141 * @deprecated Please use {@link #isFileTaggedWithAll(FileIdentifier, String[])} instead. 142 */ 143 @Deprecated 144 @WebMethod 145 @WebResult(name = "result") 146 @RequiredRoles(ROLE_RUN_HASH_QUERIES) 147 Boolean isFileTaggedWith( 148 @WebParam(name = "file") FileIdentifier file, 149 @WebParam(name = "tag") String[] tags) throws AuthenticationException; 150 151 /** 152 * Returns true if the given files are tagged with the specified tags. 153 * <p/> 154 * Implements a batch query for {@link #isFileTaggedWith(FileIdentifier, String[])}. 155 * <p/> 156 * <b>Important Note:</b> This method returned incorrect data when 'null' values were contained in the result. 157 * 'Null' values are swallowed by the XML serialization framework, because it considers the booleans 158 * as primitive types. Therefore starting from GACL 1.2, this method substitutes 'null' with 'false'. 159 * Use {@link #isFilesTaggedWithAll(BatchCollection, String[])} instead, to get a 3-way result. 160 * 161 * @param files The files to verify. 162 * @param tags The tags to check against. 163 * @return True if the tags apply to the files, false if not. 164 * @throws AuthenticationException In case of this service requires authentication and the current user session 165 * is not authenticated or doesn't have the right to access the service. 166 * @deprecated Please use {@link #isFilesTaggedWithAll(BatchCollection, String[])} instead. 167 */ 168 @Deprecated 169 @WebMethod 170 @WebResult(name = "result") 171 @RequiredRoles(ROLE_RUN_HASH_QUERIES) 172 Collection<Boolean> isFilesTaggedWith( 173 @WebParam(name = "file") BatchCollection<FileIdentifier> files, 174 @WebParam(name = "tag") String[] tags) throws AuthenticationException; 175 176 /** 177 * Returns 'Yes' if the given file is tagged with the specified tags. 178 * <p/> 179 * Example: Check whether a file is known and good:<code><pre> 180 * FileIdentifier id = new FileIdentifier(sha1Hash); 181 * switch(publicFileService.isFileTaggedWithAll(id, "clean")) { 182 * case Yes: // file is known good 183 * break; 184 * case No: // file is known bad 185 * break; 186 * case NotKnown: // file is unknown 187 * break; 188 * } 189 * </pre></code> 190 * <p/> 191 * When querying multiple files, {@link #isFilesTaggedWithAll(BatchCollection, String[])}, may be more efficient. 192 * <p/> 193 * Note: This method is a replacement for {@link #isFileTaggedWith(FileIdentifier, String[])} as a 3-way boolean 194 * is not obvious and not supported in all programming languages. 195 * 196 * @param file The file to verify. 197 * @param tags The tags to check against. 198 * @return True if the tags apply to the file, false if not, 'null' if the file is unknown. 199 * @throws AuthenticationException In case of this service requires authentication and the current user session 200 * is not authenticated or doesn't have the right to access the service. 201 */ 202 @WebMethod 203 @WebResult(name = "result") 204 @RequiredRoles(ROLE_RUN_HASH_QUERIES) 205 IsTrueResult isFileTaggedWithAll( 206 @WebParam(name = "file") FileIdentifier file, 207 @WebParam(name = "tag") String[] tags) throws AuthenticationException; 208 209 /** 210 * Returns 'Yes' if the given files are tagged with the specified tags. 211 * <p/> 212 * Implements a batch query for {@link #isFileTaggedWithAll(FileIdentifier, String[])}. 213 * <p/> 214 * Note: This method is a replacement for {@link #isFilesTaggedWith(BatchCollection, String[])} as a 3-way boolean 215 * is not obvious and not supported in all programming languages. 216 * 217 * @param files The files to verify. 218 * @param tags The tags to check against. 219 * @return a collection that contains the results of the requested files. 220 * @throws AuthenticationException In case of this service requires authentication and the current user session 221 * is not authenticated or doesn't have the right to access the service. 222 */ 223 @WebMethod 224 @WebResult(name = "result") 225 @RequiredRoles(ROLE_RUN_HASH_QUERIES) 226 Collection<IsTrueResult> isFilesTaggedWithAll( 227 @WebParam(name = "file") BatchCollection<FileIdentifier> files, 228 @WebParam(name = "tag") String[] tags) throws AuthenticationException; 229 230 /** 231 * Returns all known files that are tagged with the given list of tags. 232 * 233 * @param tags The tags to get the files for. 234 * @param pageNumber The number of the list page to return, starting from 0 for the first chunk. 235 * @return A chunk of file identifiers for the files tagged with the given tags or 236 * 'null' if no chunk exists under the given number. 237 * @throws AuthenticationException In case of this service requires authentication and the current user session 238 * is not authenticated or doesn't have the right to access the service. 239 */ 240 @WebMethod 241 @WebResult(name = "fileId") 242 @RequiredRoles(ROLE_RUN_TAG_MATCHING_QUERIES) 243 FileIdentiferListPage getFilesTaggedWith( 244 @WebParam(name = "tag") String[] tags, 245 @WebParam(name = "pageNumber") int pageNumber) throws AuthenticationException; 246 247 /** 248 * Returns all known files that are matched by the given tag expression. 249 * <p/> 250 * <b>Tag Query Grammar</b><br/> 251 * A common tag query uses a simple search grammar also common for most search engines: 252 * <ul> 253 * <li>Tags are delimited by whitespaces</li> 254 * <li>Adding "-" in front of a tag negates the search (the tag must not be included in results)</li> 255 * <li>Groups can be built by adding braces around tags. Multiple groups are combined with OR 256 * (the same as if multiple individual queries would be combined).</li> 257 * <li>Tags in one group are combined with AND (all have to be included (or excluded when prefixed with "-"))</li> 258 * </ul> 259 * The example query: {@code (mustBeInGroup1 -mustNotBeInGroup1) (mustBeInGroup2 -mustNotBeInGroup2 mustBe2InGroup2)} 260 * selects all files that were tagged with "mustBeInGroup1" but not with "mustNotBeInGroup1" and files that were 261 * tagged with "mustBeInGroup2" and "mustBe2InGroup2" but not "mustNotBeInGroup2". 262 * 263 * @param tagExpression An expression following the tag query grammar used to identify files. 264 * @param tagExpressionVersion The version of the expression (the most recent version is assumed if omitted). 265 * @param pageNumber The number of the list page to return, starting from 0 for the first chunk. 266 * @return A chunk of file identifiers for the files, matching the given expression or 267 * 'null' if no chunk exists under the given number. 268 * @throws AuthenticationException In case of this service requires authentication and the current user session 269 * is not authenticated or doesn't have the right to access the service. 270 */ 271 @WebMethod 272 @WebResult(name = "fileId") 273 @RequiredRoles(ROLE_RUN_TAG_MATCHING_QUERIES) 274 FileIdentiferListPage getMatchingFiles( 275 @WebParam(name = "tagQueryExpression") String tagExpression, 276 @WebParam(name = "tagQueryExpressionVersion") String tagExpressionVersion, 277 @WebParam(name = "pageNumber") int pageNumber) throws AuthenticationException; 278 279 /** 280 * Returns all known files that are matched by the given tag expression and are in the given range. 281 * 282 * @param tagExpression An expression following the tag query grammar used to identify files. 283 * @param tagExpressionVersion The version of the expression (the most recent version is assumed if omitted). 284 * @param range The range limiting the output. 285 * @param pageNumber The number of the list page to return, starting from 0 for the first chunk. 286 * @return A chunk of file identifiers for the files, matching the given expression or 287 * 'null' if no chunk exists under the given number. 288 * @throws AuthenticationException In case of this service requires authentication and the current user session 289 * is not authenticated or doesn't have the right to access the service. 290 */ 291 @WebMethod 292 @WebResult(name = "fileId") 293 @RequiredRoles(ROLE_RUN_TAG_MATCHING_QUERIES) 294 FileIdentiferListPage getMatchingFilesInRange( 295 @WebParam(name = "tagQueryExpression") String tagExpression, 296 @WebParam(name = "tagQueryExpressionVersion") String tagExpressionVersion, 297 @WebParam(name = "range") Range range, 298 @WebParam(name = "pageNumber") int pageNumber) throws AuthenticationException; 299 300 /** 301 * Returns the file information for the given file. 302 * 303 * @param file The file to return the information for. 304 * @return the file information for the given file or 'null' if the file is unknown. 305 * @throws AuthenticationException In case of this service requires authentication and the current user session 306 * is not authenticated or doesn't have the right to access the service. 307 */ 308 @WebMethod 309 @WebResult(name = "information") 310 @RequiredRoles(ROLE_RUN_HASH_QUERIES) 311 FileInformation getFileInformation( 312 @WebParam(name = "file") FileIdentifier file) throws AuthenticationException; 313 314 /** 315 * Returns the file information list for the given files. 316 * 317 * @param files The files to return the information list for. 318 * @return the file information list for the given file. The list may contain 'null' 319 * entries if the corresponding file was unknown. 320 * @throws AuthenticationException In case of this service requires authentication and the current user session 321 * is not authenticated or doesn't have the right to access the service. 322 */ 323 @WebMethod 324 @WebResult(name = "information") 325 @ResponseWrapper( // Adding a custom response wrapper to support 'null' values inside the returned collection. 326 className = "com.trendmicro.grid.acl.l0.wrappers.GetFileInformationListResponse") 327 @RequiredRoles(ROLE_RUN_HASH_QUERIES) 328 Collection<FileInformation> getFileInformationList( 329 @WebParam(name = "file") BatchCollection<FileIdentifier> files) throws AuthenticationException; 330 331 /** 332 * Returns the file details for the given file. 333 * 334 * @param file The file to return the details for. 335 * @return the file details for the given file or 'null' if the file is unknown. 336 * @throws AuthenticationException In case of this service requires authentication and the current user session 337 * is not authenticated or doesn't have the right to access the service. 338 */ 339 @WebMethod 340 @WebResult(name = "details") 341 @RequiredRoles({ROLE_RUN_HASH_QUERIES, ROLE_ACCESS_DETAILS}) 342 FileDetails getFileDetails( 343 @WebParam(name = "file") FileIdentifier file) throws AuthenticationException; 344 345 /** 346 * Returns the file details list for the given files. 347 * 348 * @param files The files to return the details list for. 349 * @return the file details list for the given file. The list may contain 'null' 350 * entries if the corresponding file was unknown. 351 * @throws AuthenticationException In case of this service requires authentication and the current user session 352 * is not authenticated or doesn't have the right to access the service. 353 */ 354 @WebMethod 355 @WebResult(name = "details") 356 @ResponseWrapper( // Adding a custom response wrapper to support 'null' values inside the returned collection. 357 className = "com.trendmicro.grid.acl.l0.wrappers.GetFileDetailsListResponse") 358 @RequiredRoles({ROLE_RUN_HASH_QUERIES, ROLE_ACCESS_DETAILS}) 359 Collection<FileDetails> getFileDetailsList( 360 @WebParam(name = "file") BatchCollection<FileIdentifier> files) throws AuthenticationException; 361 }