Getting Started

I don't want to code, how can I start exploring what is offered?

  • Option 1: Take a look at the method reference shown here.
  • Option 2: Try the services right away by using Eviware's SoapUI.
    You'll need SHA1 sums of files to play with the interfaces. Examples:
    289959da899bf03a34dd232ac70205df401098b0 *C:\Program Files\7-Zip\7z.exe
13a51d5b0277849065e43aa8f1451f2346376c0e *C:\Program Files\7-Zip\7z.dll

How do I query the GRID using the Unix Shell?

Bash scripts can be used for simple REST queries like "isFileKnownGood", example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
#!/bin/sh
  
gridAclHost="gacl.trendmicro.com"
gridAclAddress="http://$gridAclHost/rs/level-0/files/isKnownGood"
  
IFS=$'\n'
for file in $(sha1sum $*) ; do
    hash=$(echo $file | awk '{print $1}')
    result=$(curl -s -o - "$gridAclAddress/$hash")
  
    case "$result" in
        true)
            echo "GOOD:    $file" ;;
        false)
            echo "BAD:     $file" ;;
        *)
            echo "UNKNOWN: $file" ;;
    esac
done

How do I query the GRID using a PHP Script?

REST Example

1
2
3
4
5
6
7
8
9
10
11
12
13
<?php
  
$gridAclHost = "gacl.trendmicro.com";
$gridAclAddress = "http://$gridAclHost/rs/level-0/files/isKnownGood";
$resultMapping = array("" => "UNKNOWN:", "true" => "GOOD:   ", "false" => "BAD:    ");
  
foreach ($argv as $key => $file) {
    if ($key == 0) continue;
    $hash = sha1_file($file);
    $result = file_get_contents($gridAclAddress . "/" . $hash);
    echo $resultMapping[$result] . " $hash $file\n";
}
?>

SOAP Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
<?php
  
$gridAclHost = "gacl.trendmicro.com";
$gridAclBatchSize = 50;
$gridAclClient = new SoapClient("http://$gridAclHost/ws/level-0/files?wsdl");
  
$resultMapping = array("NotKnown" => "UNKNOWN:", "Yes" => "GOOD:   ", "No" => "BAD:    ");
$workQueue = array();
  
function processPending() {
    global $gridAclClient, $workQueue, $resultMapping;
  
    $fileIds = array();
    $files = array();
    foreach ($workQueue as $key => $hash) {
        $fileIds[] = array("sha1" => $hash);
        $files[] = $key;
    }
  
    $requestVars = array("file" => $fileIds, "tag" => array("clean"));
    $results = $gridAclClient->isFilesTaggedWithAll($requestVars);
  
    if (isset($results->result)) $results = $results->result;
    if (!is_array($results)) $results = array($results);
  
    for ($i = 0; $i < count($files); $i++)
        echo $resultMapping[$results[$i]] . " " . $files[$i] . "\n";
  
    $workQueue = array();
}
  
function enqueueFile($file, $base = "") {
    global $gridAclBatchSize, $workQueue;
  
    if (is_array($file))
        foreach ($file as $f) enqueueFile($f, $base);
    else {
        if (strpos($file, ".") === 0)
            return;
        if (is_dir($base . $file))
            enqueueFile(scandir($base . $file), $base . $file . "/");
        else {
            $workQueue[$base . $file] = sha1_file($base . $file);
            if (count($workQueue) == $gridAclBatchSize) processPending();
        }
    }
}
  
foreach ($argv as $key => $file) {
    if ($key == 0) continue;
    enqueueFile($file);
}
processPending();
?>

How do I query the GRID using a Groovy Script?

Multi-threaded REST client example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
import java.security.*
import java.util.concurrent.*
  
this.gridAclHost = "gacl.trendmicro.com";
this.gridAclAddress = "http://$gridAclHost/rs/level-0/files/isKnownGood";
this.gridAclConnectionCount = 4;
  
this.resultMapping = ["": "UNKNOWN:", "true": "GOOD:   ", "false": "BAD:    "];
this.workQueue = new ArrayBlockingQueue(500);
  
def createHash(File file, def hashType) {
    return file.withInputStream { is ->
        def digest = MessageDigest.getInstance(hashType);
        new DigestInputStream(is, digest).eachByte(4096) { buf, len -> /* do nothing */ };
        return new BigInteger(1, digest.digest()).toString(16).padLeft(40, '0');
    }
}
  
def enqueueFile(File file) {
    if (file.isDirectory())
        file.eachFile { f -> enqueueFile(f); }
    else
        workQueue.put([file, createHash(file, "SHA1")]);
}
  
for (int i = 0; i < gridAclConnectionCount; i++) {
    new Thread("Connection Worker #$i").startDaemon {
        while (!Thread.currentThread().isInterrupted()) {
            def work = workQueue.take();
            def result = new URL(gridAclAddress + "/" + work[1]).text;
            println(resultMapping[result] + work[1] + " " + work[0]);
        }
    };
}
  
this.args.each { arg -> enqueueFile(new File(arg)); }
while (!workQueue.isEmpty()) Thread.sleep(500);

How do I query the GRID using Java?

1 Step: Setup a Project and Generate Stubs

  • Option 1: Use the offered java client library.
  • Option 2: Use a Wizard provided by the IDE using one of the WSDL or WADL urls (easy but binds project to the used IDE)
  • Option 3: Setup Maven (or a comparable tool) with JAX-WS (or similar) bindings that builds the stubs dynamically before every build.

    Automate downloading WSDLs and building the stubs with "Maven & JAX-WS":

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    <?xml version="1.0" encoding="UTF-8"?>
    <project xmlns="http://maven.apache.org/POM/4.0.0"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
             http://maven.apache.org/xsd/maven-4.0.0.xsd">
        ...
      
        <properties>
            <gacl.url>https://mygacl.trendmicro.com/ws/level-0/</gacl.url>
        </properties>
      
        <build>
            <plugins>
                <plugin>
                    <groupId>org.codehaus.mojo</groupId>
                    <artifactId>jaxws-maven-plugin</artifactId>
                    <version>1.10</version>
                    <executions>
                        <execution>
                            <id>PublicServices</id>
                            <goals>
                                <goal>wsimport</goal>
                            </goals>
                            <configuration>
                                <packageName>com.trendmicro.grid.acl</packageName>
                                <wsdlUrls>
                                    <wsdlUrl>${gacl.url}/authentication?wsdl</wsdlUrl>
                                    <wsdlUrl>${gacl.url}/categories?wsdl</wsdlUrl>
                                    <wsdlUrl>${gacl.url}/files?wsdl</wsdlUrl>
                                    <wsdlUrl>${gacl.url}/packages?wsdl</wsdlUrl>
                                    <wsdlUrl>${gacl.url}/reporting?wsdl</wsdlUrl>
                                </wsdlUrls>
                            </configuration>
                        </execution>
                    </executions>
                </plugin>
            </plugins>
        </build>
    </project>

2 Step: Use the API

How do I query the GRID using C#?

1 Step: Setup a Project and Generate Stubs

  • Option 1: Use a Wizard provided by the IDE using one of the WSDL or WADL urls (easy but binds project to the used IDE)
  • Option 2: Setup a batch or NANT script with "disco.exe / wsdl.exe" bindings that builds the stubs dynamically before every build:

    Automate downloading the WSDLs with "disco.exe":

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    @echo off
    REM -------------------------------------------------------------------
    REM Updates the WSDLs and XSDs with the latest definitions from the ACL
    REM --> Call this when the interfaces inside ACL changed.
    REM -------------------------------------------------------------------
      
    mkdir authentication
    mkdir categories
    mkdir files
    mkdir packages
    mkdir reporting
      
    disco /o:authentication https://mygacl.trendmicro.com/ws/level-0/authentication?wsdl
    disco /o:categories https://mygacl.trendmicro.com/ws/level-0/categories?wsdl
    disco /o:files https://mygacl.trendmicro.com/ws/level-0/files?wsdl
    disco /o:packages https://mygacl.trendmicro.com/ws/level-0/packages?wsdl
    disco /o:reporting https://mygacl.trendmicro.com/ws/level-0/reporting?wsdl

    Automate building the stubs with "wsdl.exe":

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    @echo off
    REM -------------------------------------------------------------------
    REM Generates the ACLClient classes needed to call ACL SOAP methods.
    REM --> This is called in the pre-processing step of every build.
    REM     Do not check-in the generated classes into VCS.
    REM     Customization can be achieved by sub-classing or extending the
    REM     partial classes.
    REM -------------------------------------------------------------------
      
    setlocal
      
    set CLIENT_CLASS=..\GRID\ACLClient\Generated.ACLClient.cs
    set CMD=wsdl /out:%CLIENT_CLASS% /namespace:TrendMicro.GRID.ACLClient /sharetypes
      
    REM Defines Services to include
    set CMD=%CMD% authentication\results.discomap
    set CMD=%CMD% categories\results.discomap
    set CMD=%CMD% files\results.discomap
    set CMD=%CMD% packages\results.discomap
    set CMD=%CMD% reporting\results.discomap
      
    REM Build the client
    echo %CMD%
    call %CMD%
      
    endlocal

2 Step: Use the API