Skip to content

Commit 02a74a2

Browse files
su-amaas830d953e
su-amaas
authored and
830d953e
committed
update to latest version: v1.2.0
1 parent 92bf591 commit 02a74a2

File tree

8 files changed

+106
-28
lines changed

8 files changed

+106
-28
lines changed

‎CHANGELOG.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# CHANGELOG
22

3+
## 1.2.0 - 2024-07-05
4+
5+
* Support verbose scan result
6+
37
## 1.1.1 - 2024-04-10
48

59
* Update README.md

‎README.md‎

Lines changed: 82 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,7 @@ for scan_result in scan_results:
9797
```
9898

9999
### Sample JSON Response
100+
#### Concise Format
100101

101102
```json
102103
{
@@ -116,6 +117,71 @@ for scan_result in scan_results:
116117
"fileSHA256": "7dddcd0f64165f51291a41f49b6246cf85c3e6e599c096612cccce09566091f2"
117118
}
118119
```
120+
#### Verbose Format
121+
```json
122+
{
123+
"scanType": "sdk",
124+
"objectType": "file",
125+
"timestamp": {
126+
"start": "2024-04-26T18:43:48.639Z",
127+
"end": "2024-04-26T18:43:49.941Z"
128+
},
129+
"schemaVersion": "1.0.0",
130+
"scannerVersion": "1.0.0-1",
131+
"fileName": "TRENDX_detect.exe",
132+
"rsSize": 356352,
133+
"scanId": "84947a19-b84a-4091-bb7d-8422ab5098a7",
134+
"accountId": "7423a980-b5af-4e28-bf0b-b58cdf623bb8",
135+
"result": {
136+
"atse": {
137+
"elapsedTime": 1004335,
138+
"fileType": 7,
139+
"fileSubType": 2,
140+
"version": {
141+
"engine": "23.57.0-1002",
142+
"lptvpn": 301,
143+
"ssaptn": 721,
144+
"tmblack": 253,
145+
"tmwhite": 227,
146+
"macvpn": 904
147+
},
148+
"malwareCount": 0,
149+
"malware": null,
150+
"error": null,
151+
"fileTypeName": "EXE",
152+
"fileSubTypeName": "VSDT_EXE_W32"
153+
},
154+
"trendx": {
155+
"elapsedTime": 296763,
156+
"fileType": 7,
157+
"fileSubType": 2,
158+
"version": {
159+
"engine": "23.57.0-1002",
160+
"tmblack": 253,
161+
"trendx": 331
162+
},
163+
"malwareCount": 1,
164+
"malware": [
165+
{
166+
"name": "Ransom.Win32.TRX.XXPE1",
167+
"fileName": "TRENDX_detect.exe",
168+
"type": "Ransom",
169+
"fileType": 7,
170+
"fileSubType": 2,
171+
"fileTypeName": "EXE",
172+
"fileSubTypeName": "VSDT_EXE_W32"
173+
}
174+
],
175+
"error": null,
176+
"fileTypeName": "EXE",
177+
"fileSubTypeName": "VSDT_EXE_W32"
178+
}
179+
},
180+
"fileSHA1": "b448479b0a6a5d387c71600e1b75700ba7f42b0a",
181+
"fileSHA256": "4b7593109f81b5a770d440d8c28fa1457cd4b95d51b5d049fb301fc99c41da39",
182+
"appName": "V1FS"
183+
}
184+
```
119185

120186
When malicious content is detected in the scanned object, `scanResult` will show a non-zero value. Otherwise, the value will be `null`. Moreover, when malware is detected, `foundMalwares` will be non-empty containing one or more name/value pairs of `fileName` and `malwareName`. `fileName` will be filename of malware detected while `malwareName` will be the name of the virus/malware found.
121187

@@ -130,11 +196,11 @@ Creates a new instance of the grpc Channel, and provisions essential settings, i
130196
**_Parameters_**
131197

132198
| Parameter | Description |
133-
|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
199+
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
134200
| region | The region you obtained your api key. Value provided must be one of the Vision One regions, e.g. `us-east-1`, `eu-central-1`, `ap-northeast-1`, `ap-southeast-2`, `ap-southeast-1`, `ap-south-1`, etc. |
135201
| api_key | Your own Vision One API Key. |
136-
| enable_tls | Enable or disable TLS. TLS should always be enabled when connecting to the AMaaS server. For more information, see the 'Ensuring Secure Communication with TLS' section. |
137-
| ca_cert | `Optional` CA certificate used to connect to AMaaS server. |
202+
| enable_tls | Enable or disable TLS. TLS should always be enabled when connecting to the AMaaS server. For more information, see the 'Ensuring Secure Communication with TLS' section. |
203+
| ca_cert | `Optional` CA certificate used to connect to AMaaS server. |
138204

139205
**_Return_**
140206
A grpc Channel instance
@@ -146,47 +212,49 @@ Creates a new instance of the grpc aio Channel, and provisions essential setting
146212
**_Parameters_**
147213

148214
| Parameter | Description |
149-
|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
215+
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
150216
| region | The region you obtained your api key. Value provided must be one of the Vision One regions, e.g. `us-east-1`, `eu-central-1`, `ap-northeast-1`, `ap-southeast-2`, `ap-southeast-1`, `ap-south-1`, etc. |
151217
| api_key | Your own Vision One API Key. |
152-
| enable_tls | Enable or disable TLS. TLS should always be enabled when connecting to the AMaaS server. For more information, see the 'Ensuring Secure Communication with TLS' section. |
153-
| ca_cert | `Optional` CA certificate used to connect to AMaaS server. |
218+
| enable_tls | Enable or disable TLS. TLS should always be enabled when connecting to the AMaaS server. For more information, see the 'Ensuring Secure Communication with TLS' section. |
219+
| ca_cert | `Optional` CA certificate used to connect to AMaaS server. |
154220

155221
**_Return_**
156222
A grpc aio Channel instance
157223

158224
### Scan
159225

160-
#### ```def amaas.grpc.scan_file(handle: grpc.Channel, file_name: str, tags: List[str], pml: bool = False, feedback: bool = False) -> str```
226+
#### ```def amaas.grpc.scan_file(handle: grpc.Channel, file_name: str, tags: List[str], pml: bool = False, feedback: bool = False, verbose: bool = False) -> str```
161227

162228
Scan a file for malware and retrieves response data from the API.
163229

164230
**_Parameters_**
165231

166232
| Parameter | Description |
167-
|-----------|-------------------------------------------------------------------------------------------------------------|
233+
| --------- | ----------------------------------------------------------------------------------------------------------- |
168234
| handle | The grpc Channel instance was created from the init function. |
169235
| file_name | The name of the file with the path of the directory containing the file to scan. |
170236
| tags | A list of strings to be used to tag the scan result. At most 8 tags with a maximum length of 63 characters. |
171237
| pml | Enable PML (Predictive Machine Learning) Detection. |
172238
| feedback | Enable SPN feedback for Predictive Machine Learning Detection |
239+
| verbose | Enable log verbose mode |
173240

174241
**_Return_**
175242
String the scanned result in JSON format.
176243

177-
#### ```def amaas.grpc.aio.scan_file(handle: grpc.aio.Channel, file_name: str, tags: List[str], pml: bool = False, feedback: bool = False) -> str```
244+
#### ```def amaas.grpc.aio.scan_file(handle: grpc.aio.Channel, file_name: str, tags: List[str], pml: bool = False, feedback: bool = False, verbose: bool = False) -> str```
178245

179246
AsyncIO Scan a file for malware and retrieves response data from the API.
180247

181248
**_Parameters_**
182249

183250
| Parameter | Description |
184-
|-----------|-------------------------------------------------------------------------------------------------------------|
251+
| --------- | ----------------------------------------------------------------------------------------------------------- |
185252
| handle | The grpc aio Channel instance was created from the init function. |
186253
| file_name | The name of the file with the path of the directory containing the file to scan. |
187254
| tags | A list of strings to be used to tag the scan result. At most 8 tags with a maximum length of 63 characters. |
188255
| pml | Enable PML (Predictive Machine Learning) Detection. |
189256
| feedback | Enable SPN feedback for Predictive Machine Learning Detection |
257+
| verbose | Enable log verbose mode |
190258

191259
**_Return_**
192260
String the scanned result in JSON format.
@@ -200,7 +268,7 @@ Remember to clean up the grpc Channel when you are done using it to release any
200268
**_Parameters_**
201269

202270
| Parameter | Description |
203-
|-----------|-----------------------------------------------------------|
271+
| --------- | --------------------------------------------------------- |
204272
| handle | The grpc Channel instance created from the init function. |
205273

206274
#### ```def amaas.grpc.aio.quit(handle: grpc.aio.Channel) -> None```
@@ -210,15 +278,15 @@ Remember to clean up the grpc aio Channel when you are done using it to release
210278
**_Parameters_**
211279

212280
| Parameter | Description |
213-
|-----------|---------------------------------------------------------------|
281+
| --------- | ------------------------------------------------------------- |
214282
| handle | The grpc aio Channel instance created from the init function. |
215283

216284
## Environment Variables
217285

218286
The following environment variables are supported by Python Client SDK and can be used in lieu of values specified as function arguments.
219287

220288
| Variable Name | Description & Purpose | Valid Values |
221-
|---------------------------|----------------------------------------------------------------------------|----------------------------|
289+
| ------------------------- | -------------------------------------------------------------------------- | -------------------------- |
222290
| `TM_AM_SCAN_TIMEOUT_SECS` | Specify, in number of seconds, to override the default scan timeout period | 0, 1, 2, ... ; default=300 |
223291

224292
## Thread Safety
@@ -230,4 +298,4 @@ The following environment variables are supported by Python Client SDK and can b
230298
The communication channel between the client program or SDK and the Trend Vision One™ File Security service is fortified with robust server-side TLS encryption. This ensures that all data transmitted between the client and Trend service remains thoroughly encrypted and safeguarded.
231299
The certificate employed by server-side TLS is a publicly-signed certificate from Trend Micro Inc, issued by a trusted Certificate Authority (CA), further bolstering security measures.
232300

233-
The File Security SDK consistently adopts TLS as the default communication channel, prioritizing security at all times. It is strongly advised not to disable TLS in a production environment while utilizing the File Security SDK, as doing so could compromise the integrity and confidentiality of transmitted data.
301+
The File Security SDK consistently adopts TLS as the default communication channel, prioritizing security at all times. It is strongly advised not to disable TLS in a production environment while utilizing the File Security SDK, as doing so could compromise the integrity and confidentiality of transmitted data.

‎VERSION‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
1.1.1
1+
1.2.0

‎amaas/grpc/__init__.py‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -122,7 +122,7 @@ def quit(handle):
122122

123123

124124
def _scan_data(channel: grpc.Channel, data_reader: BinaryIO, size: int, identifier: str, tags: List[str],
125-
pml: bool, feedback: bool) -> str:
125+
pml: bool, feedback: bool, verbose: bool) -> str:
126126
_validate_tags(tags)
127127
stub = scan_pb2_grpc.ScanStub(channel)
128128
pipeline = _Pipeline()
@@ -146,7 +146,8 @@ def _scan_data(channel: grpc.Channel, data_reader: BinaryIO, size: int, identifi
146146
file_sha1="sha1:" + _digest_hex(data_reader, "sha1"),
147147
file_sha256="sha256:" + _digest_hex(data_reader, "sha256"),
148148
bulk=bulk,
149-
spn_feedback=feedback)
149+
spn_feedback=feedback,
150+
verbose=verbose)
150151

151152
pipeline.set_message(message)
152153

@@ -181,7 +182,7 @@ def _scan_data(channel: grpc.Channel, data_reader: BinaryIO, size: int, identifi
181182

182183

183184
def scan_file(channel: grpc.Channel, file_name: str, tags: List[str] = None,
184-
pml: bool = False, feedback: bool = False) -> str:
185+
pml: bool = False, feedback: bool = False, verbose: bool = False) -> str:
185186
try:
186187
f = open(file_name, "rb")
187188
fid = os.path.basename(file_name)
@@ -193,10 +194,10 @@ def scan_file(channel: grpc.Channel, file_name: str, tags: List[str] = None,
193194
logger.debug("Permission error: " + str(err))
194195
raise AMaasException(AMaasErrorCode.MSG_ID_ERR_FILE_NO_PERMISSION, file_name)
195196

196-
return _scan_data(channel, f, n, fid, tags, pml, feedback)
197+
return _scan_data(channel, f, n, fid, tags, pml, feedback, verbose)
197198

198199

199200
def scan_buffer(channel: grpc.Channel, bytes_buffer: bytes, uid: str, tags: List[str] = None,
200-
pml: bool = False, feedback: bool = False) -> str:
201+
pml: bool = False, feedback: bool = False, verbose: bool = False) -> str:
201202
f = io.BytesIO(bytes_buffer)
202-
return _scan_data(channel, f, len(bytes_buffer), uid, tags, pml, feedback)
203+
return _scan_data(channel, f, len(bytes_buffer), uid, tags, pml, feedback, verbose)

‎amaas/grpc/aio/__init__.py‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ async def quit(handle):
4040

4141

4242
async def _scan_data(channel: grpc.Channel, data_reader: BinaryIO, size: int, identifier: str, tags: List[str],
43-
pml: bool, feedback: bool) -> str:
43+
pml: bool, feedback: bool, verbose: bool) -> str:
4444
_validate_tags(tags)
4545
stub = scan_pb2_grpc.ScanStub(channel)
4646
stats = {}
@@ -63,7 +63,8 @@ async def _scan_data(channel: grpc.Channel, data_reader: BinaryIO, size: int, id
6363
file_sha1="sha1:" + _digest_hex(data_reader, "sha1"),
6464
file_sha256="sha256:" + _digest_hex(data_reader, "sha256"),
6565
bulk=bulk,
66-
spn_feedback=feedback)
66+
spn_feedback=feedback,
67+
verbose=verbose)
6768

6869
await call.write(request)
6970

@@ -139,7 +140,7 @@ async def _scan_data(channel: grpc.Channel, data_reader: BinaryIO, size: int, id
139140

140141

141142
async def scan_file(channel: grpc.Channel, file_name: str, tags: List[str] = None,
142-
pml: bool = False, feedback: bool = False) -> str:
143+
pml: bool = False, feedback: bool = False, verbose: bool = False) -> str:
143144
try:
144145
f = open(file_name, "rb")
145146
fid = os.path.basename(file_name)
@@ -150,10 +151,10 @@ async def scan_file(channel: grpc.Channel, file_name: str, tags: List[str] = Non
150151
except (PermissionError, IOError) as err:
151152
logger.debug("Permission error: " + str(err))
152153
raise AMaasException(AMaasErrorCode.MSG_ID_ERR_FILE_NO_PERMISSION, file_name)
153-
return await _scan_data(channel, f, n, fid, tags, pml, feedback)
154+
return await _scan_data(channel, f, n, fid, tags, pml, feedback, verbose)
154155

155156

156157
async def scan_buffer(channel: grpc.Channel, bytes_buffer: bytes, uid: str, tags: List[str] = None,
157-
pml: bool = False, feedback: bool = False) -> str:
158+
pml: bool = False, feedback: bool = False, verbose: bool = False) -> str:
158159
f = io.BytesIO(bytes_buffer)
159-
return await _scan_data(channel, f, len(bytes_buffer), uid, tags, pml, feedback)
160+
return await _scan_data(channel, f, len(bytes_buffer), uid, tags, pml, feedback, verbose)

‎examples/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,7 @@ If you plan on using a Trend Vision One region, be sure to pass in region parame
6060
| --filename or -f | File to be scanned | No |
6161
| --pml | Predictive Machine Learning | Yes |
6262
| --tags or -t | List of tags | Yes |
63+
| --verbose or -v | Log verbose mode | Yes |
6364

6465
4. Run one of the examples.
6566

‎examples/client.py‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,8 @@
2626
help='list of tags')
2727
parser.add_argument('--feedback', action=argparse.BooleanOptionalAction, default=False,
2828
help='enable feedback for predictive machine learning detection')
29+
parser.add_argument('-v', '--verbose', action=argparse.BooleanOptionalAction, default=False,
30+
help='enable log verbose mode')
2931

3032
args = parser.parse_args()
3133

@@ -37,7 +39,7 @@
3739
s = time.perf_counter()
3840

3941
try:
40-
result = amaas.grpc.scan_file(handle, file_name=args.filename, pml=args.pml, tags=args.tags, feedback=args.feedback)
42+
result = amaas.grpc.scan_file(handle, file_name=args.filename, pml=args.pml, tags=args.tags, feedback=args.feedback, verbose=args.verbose)
4143
elapsed = time.perf_counter() - s
4244
print(f"scan executed in {elapsed:0.2f} seconds.")
4345
print(result)

‎protos/scan.proto‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ message C2S {
2929
repeated string tags = 9;
3030
bool bulk = 10;
3131
bool spn_feedback = 11;
32+
bool verbose = 12;
3233
}
3334

3435
enum Command {

0 commit comments

Comments
 (0)