Skip to content

Commit

Permalink
update to latest version: v1.2.0
Browse files Browse the repository at this point in the history
  • Loading branch information
@su-amaas @830d953e
su-amaas authored and 830d953e committed Jul 8, 2024
1 parent 92bf591 commit 02a74a2
Show file tree
Hide file tree
Showing 8 changed files with 106 additions and 28 deletions.
4 changes: 4 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,9 @@
# CHANGELOG

## 1.2.0 - 2024-07-05

* Support verbose scan result

## 1.1.1 - 2024-04-10

* Update README.md
Expand Down
96 changes: 82 additions & 14 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,7 @@ for scan_result in scan_results:
```
### Sample JSON Response
#### Concise Format
```json
{
Expand All @@ -116,6 +117,71 @@ for scan_result in scan_results:
"fileSHA256": "7dddcd0f64165f51291a41f49b6246cf85c3e6e599c096612cccce09566091f2"
}
```
#### Verbose Format
```json
{
"scanType": "sdk",
"objectType": "file",
"timestamp": {
"start": "2024-04-26T18:43:48.639Z",
"end": "2024-04-26T18:43:49.941Z"
},
"schemaVersion": "1.0.0",
"scannerVersion": "1.0.0-1",
"fileName": "TRENDX_detect.exe",
"rsSize": 356352,
"scanId": "84947a19-b84a-4091-bb7d-8422ab5098a7",
"accountId": "7423a980-b5af-4e28-bf0b-b58cdf623bb8",
"result": {
"atse": {
"elapsedTime": 1004335,
"fileType": 7,
"fileSubType": 2,
"version": {
"engine": "23.57.0-1002",
"lptvpn": 301,
"ssaptn": 721,
"tmblack": 253,
"tmwhite": 227,
"macvpn": 904
},
"malwareCount": 0,
"malware": null,
"error": null,
"fileTypeName": "EXE",
"fileSubTypeName": "VSDT_EXE_W32"
},
"trendx": {
"elapsedTime": 296763,
"fileType": 7,
"fileSubType": 2,
"version": {
"engine": "23.57.0-1002",
"tmblack": 253,
"trendx": 331
},
"malwareCount": 1,
"malware": [
{
"name": "Ransom.Win32.TRX.XXPE1",
"fileName": "TRENDX_detect.exe",
"type": "Ransom",
"fileType": 7,
"fileSubType": 2,
"fileTypeName": "EXE",
"fileSubTypeName": "VSDT_EXE_W32"
}
],
"error": null,
"fileTypeName": "EXE",
"fileSubTypeName": "VSDT_EXE_W32"
}
},
"fileSHA1": "b448479b0a6a5d387c71600e1b75700ba7f42b0a",
"fileSHA256": "4b7593109f81b5a770d440d8c28fa1457cd4b95d51b5d049fb301fc99c41da39",
"appName": "V1FS"
}
```
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.
Expand All @@ -130,11 +196,11 @@ Creates a new instance of the grpc Channel, and provisions essential settings, i
**_Parameters_**
| Parameter | Description |
|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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. |
| api_key | Your own Vision One API Key. |
| 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. |
| ca_cert | `Optional` CA certificate used to connect to AMaaS server. |
| 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. |
| ca_cert | `Optional` CA certificate used to connect to AMaaS server. |
**_Return_**
A grpc Channel instance
Expand All @@ -146,47 +212,49 @@ Creates a new instance of the grpc aio Channel, and provisions essential setting
**_Parameters_**
| Parameter | Description |
|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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. |
| api_key | Your own Vision One API Key. |
| 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. |
| ca_cert | `Optional` CA certificate used to connect to AMaaS server. |
| 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. |
| ca_cert | `Optional` CA certificate used to connect to AMaaS server. |
**_Return_**
A grpc aio Channel instance
### Scan
#### ```def amaas.grpc.scan_file(handle: grpc.Channel, file_name: str, tags: List[str], pml: bool = False, feedback: bool = False) -> str```
#### ```def amaas.grpc.scan_file(handle: grpc.Channel, file_name: str, tags: List[str], pml: bool = False, feedback: bool = False, verbose: bool = False) -> str```
Scan a file for malware and retrieves response data from the API.
**_Parameters_**
| Parameter | Description |
|-----------|-------------------------------------------------------------------------------------------------------------|
| --------- | ----------------------------------------------------------------------------------------------------------- |
| handle | The grpc Channel instance was created from the init function. |
| file_name | The name of the file with the path of the directory containing the file to scan. |
| tags | A list of strings to be used to tag the scan result. At most 8 tags with a maximum length of 63 characters. |
| pml | Enable PML (Predictive Machine Learning) Detection. |
| feedback | Enable SPN feedback for Predictive Machine Learning Detection |
| verbose | Enable log verbose mode |
**_Return_**
String the scanned result in JSON format.
#### ```def amaas.grpc.aio.scan_file(handle: grpc.aio.Channel, file_name: str, tags: List[str], pml: bool = False, feedback: bool = False) -> str```
#### ```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```
AsyncIO Scan a file for malware and retrieves response data from the API.
**_Parameters_**
| Parameter | Description |
|-----------|-------------------------------------------------------------------------------------------------------------|
| --------- | ----------------------------------------------------------------------------------------------------------- |
| handle | The grpc aio Channel instance was created from the init function. |
| file_name | The name of the file with the path of the directory containing the file to scan. |
| tags | A list of strings to be used to tag the scan result. At most 8 tags with a maximum length of 63 characters. |
| pml | Enable PML (Predictive Machine Learning) Detection. |
| feedback | Enable SPN feedback for Predictive Machine Learning Detection |
| verbose | Enable log verbose mode |
**_Return_**
String the scanned result in JSON format.
Expand All @@ -200,7 +268,7 @@ Remember to clean up the grpc Channel when you are done using it to release any
**_Parameters_**
| Parameter | Description |
|-----------|-----------------------------------------------------------|
| --------- | --------------------------------------------------------- |
| handle | The grpc Channel instance created from the init function. |
#### ```def amaas.grpc.aio.quit(handle: grpc.aio.Channel) -> None```
Expand All @@ -210,15 +278,15 @@ Remember to clean up the grpc aio Channel when you are done using it to release
**_Parameters_**
| Parameter | Description |
|-----------|---------------------------------------------------------------|
| --------- | ------------------------------------------------------------- |
| handle | The grpc aio Channel instance created from the init function. |
## Environment Variables
The following environment variables are supported by Python Client SDK and can be used in lieu of values specified as function arguments.
| Variable Name | Description & Purpose | Valid Values |
|---------------------------|----------------------------------------------------------------------------|----------------------------|
| ------------------------- | -------------------------------------------------------------------------- | -------------------------- |
| `TM_AM_SCAN_TIMEOUT_SECS` | Specify, in number of seconds, to override the default scan timeout period | 0, 1, 2, ... ; default=300 |
## Thread Safety
Expand All @@ -230,4 +298,4 @@ The following environment variables are supported by Python Client SDK and can b
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.
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.
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.
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.
2 changes: 1 addition & 1 deletion VERSION
View file
Original file line number Diff line number Diff line change
@@ -1 +1 @@
1.1.1
1.2.0
13 changes: 7 additions & 6 deletions amaas/grpc/__init__.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -122,7 +122,7 @@ def quit(handle):


def _scan_data(channel: grpc.Channel, data_reader: BinaryIO, size: int, identifier: str, tags: List[str],
pml: bool, feedback: bool) -> str:
pml: bool, feedback: bool, verbose: bool) -> str:
_validate_tags(tags)
stub = scan_pb2_grpc.ScanStub(channel)
pipeline = _Pipeline()
Expand All @@ -146,7 +146,8 @@ def _scan_data(channel: grpc.Channel, data_reader: BinaryIO, size: int, identifi
file_sha1="sha1:" + _digest_hex(data_reader, "sha1"),
file_sha256="sha256:" + _digest_hex(data_reader, "sha256"),
bulk=bulk,
spn_feedback=feedback)
spn_feedback=feedback,
verbose=verbose)

pipeline.set_message(message)

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


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

return _scan_data(channel, f, n, fid, tags, pml, feedback)
return _scan_data(channel, f, n, fid, tags, pml, feedback, verbose)


def scan_buffer(channel: grpc.Channel, bytes_buffer: bytes, uid: str, tags: List[str] = None,
pml: bool = False, feedback: bool = False) -> str:
pml: bool = False, feedback: bool = False, verbose: bool = False) -> str:
f = io.BytesIO(bytes_buffer)
return _scan_data(channel, f, len(bytes_buffer), uid, tags, pml, feedback)
return _scan_data(channel, f, len(bytes_buffer), uid, tags, pml, feedback, verbose)
13 changes: 7 additions & 6 deletions amaas/grpc/aio/__init__.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ async def quit(handle):


async def _scan_data(channel: grpc.Channel, data_reader: BinaryIO, size: int, identifier: str, tags: List[str],
pml: bool, feedback: bool) -> str:
pml: bool, feedback: bool, verbose: bool) -> str:
_validate_tags(tags)
stub = scan_pb2_grpc.ScanStub(channel)
stats = {}
Expand All @@ -63,7 +63,8 @@ async def _scan_data(channel: grpc.Channel, data_reader: BinaryIO, size: int, id
file_sha1="sha1:" + _digest_hex(data_reader, "sha1"),
file_sha256="sha256:" + _digest_hex(data_reader, "sha256"),
bulk=bulk,
spn_feedback=feedback)
spn_feedback=feedback,
verbose=verbose)

await call.write(request)

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


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


async def scan_buffer(channel: grpc.Channel, bytes_buffer: bytes, uid: str, tags: List[str] = None,
pml: bool = False, feedback: bool = False) -> str:
pml: bool = False, feedback: bool = False, verbose: bool = False) -> str:
f = io.BytesIO(bytes_buffer)
return await _scan_data(channel, f, len(bytes_buffer), uid, tags, pml, feedback)
return await _scan_data(channel, f, len(bytes_buffer), uid, tags, pml, feedback, verbose)
1 change: 1 addition & 0 deletions examples/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,7 @@ If you plan on using a Trend Vision One region, be sure to pass in region parame
| --filename or -f | File to be scanned | No |
| --pml | Predictive Machine Learning | Yes |
| --tags or -t | List of tags | Yes |
| --verbose or -v | Log verbose mode | Yes |

4. Run one of the examples.

Expand Down
4 changes: 3 additions & 1 deletion examples/client.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,8 @@
help='list of tags')
parser.add_argument('--feedback', action=argparse.BooleanOptionalAction, default=False,
help='enable feedback for predictive machine learning detection')
parser.add_argument('-v', '--verbose', action=argparse.BooleanOptionalAction, default=False,
help='enable log verbose mode')

args = parser.parse_args()

Expand All @@ -37,7 +39,7 @@
s = time.perf_counter()

try:
result = amaas.grpc.scan_file(handle, file_name=args.filename, pml=args.pml, tags=args.tags, feedback=args.feedback)
result = amaas.grpc.scan_file(handle, file_name=args.filename, pml=args.pml, tags=args.tags, feedback=args.feedback, verbose=args.verbose)
elapsed = time.perf_counter() - s
print(f"scan executed in {elapsed:0.2f} seconds.")
print(result)
Expand Down
1 change: 1 addition & 0 deletions protos/scan.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ message C2S {
repeated string tags = 9;
bool bulk = 10;
bool spn_feedback = 11;
bool verbose = 12;
}

enum Command {
Expand Down

0 comments on commit 02a74a2

Please sign in to comment.