update to latest version: v1.5.0

Author: su-amaas

CHANGELOG.md

@@ -1,5 +1,9 @@
 # CHANGELOG
 
+## 1.5.0 - 2024-12-16
+* Add `ScanReader` for scanning a well-implemented `AmaasClientReader`
+* Add example code `scan-s3obj` for scanning an S3 object which is an example of using `ScanReader`
+
 ## 1.4.2 - 2024-08-30
 
 * Fixed the issue of the TLS parameter being overwritten

README.md

@@ -102,9 +102,50 @@ if err != nil {
 // Use the 'response' as needed
 ```
 
+### Scanning with AmaasClientReader
+
+```go
+type CustomReader struct {
+    ...
+}
+
+func newCustomReader() *CustomReader {
+    ...
+}
+
+func (r *CustomReader) Identifier() string {
+    // It returns the name of the file.
+}
+
+func (r *CustomReader) DataSize() (int64, error) {
+    // It should return the true size of the file in Reader.
+}
+
+func (r *CustomReader) ReadBytes(offset int64, length int32) (data []byte, err error) {
+    // It should return required number of data bytes starting from certain offset.
+}
+
+reader := newCustomReader()
+
+// It is recommended to disable digest when using AmaasReader.
+// Because it will trigger ReadBytes to read whole file,
+// network traffic will increase if it reads from the Internet.
+client.SetDigestDisable()
+
+response, err := client.ScanReader(reader, tags)
+if err != nil {
+    // Handle scanning error
+    panic(err)
+}
+
+// Use the 'response' as needed
+```
+
 **_Note_**
 
 - Max number of tags is 8. And the length of each tag can't exceed 63.
+- If user wants to take a look how to scan a S3 file without downloading the whole to the ground,
+  please refer to the [example code](examples/scan-s3obj/scan-s3obj.go) for further detail.
 
 ## Additional Functions
 

VERSION

@@ -1 +1 @@
-1.4.2
+1.5.0

examples/scan-s3obj/go.mod

@@ -0,0 +1,36 @@
+module github.com/trendmicro/tm-v1-fs-golang-sdk/examples/scan-s3obj
+
+go 1.23
+
+require (
+	github.com/aws/aws-sdk-go-v2 v1.32.5 // indirect
+	github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.6.7 // indirect
+	github.com/aws/aws-sdk-go-v2/credentials v1.17.46 // indirect
+	github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.16.20 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/configsources v1.3.24 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.6.24 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/ini v1.8.1 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/v4a v1.3.24 // indirect
+	github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.12.1 // indirect
+	github.com/aws/aws-sdk-go-v2/service/internal/checksum v1.4.5 // indirect
+	github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.12.5 // indirect
+	github.com/aws/aws-sdk-go-v2/service/internal/s3shared v1.18.5 // indirect
+	github.com/aws/aws-sdk-go-v2/service/sso v1.24.6 // indirect
+	github.com/aws/aws-sdk-go-v2/service/ssooidc v1.28.5 // indirect
+	github.com/aws/aws-sdk-go-v2/service/sts v1.33.1 // indirect
+	github.com/aws/smithy-go v1.22.1 // indirect
+	github.com/golang/protobuf v1.5.4 // indirect
+	golang.org/x/exp v0.0.0-20231006140011-7918f672742d // indirect
+	golang.org/x/net v0.22.0 // indirect
+	golang.org/x/sys v0.18.0 // indirect
+	golang.org/x/text v0.14.0 // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20240311173647-c811ad7063a7 // indirect
+	google.golang.org/grpc v1.62.1 // indirect
+	google.golang.org/protobuf v1.33.0 // indirect
+)
+
+require (
+	github.com/trendmicro/tm-v1-fs-golang-sdk v0.0.0-20241119105152-8e5832d37e21
+	github.com/aws/aws-sdk-go-v2/config v1.28.5
+	github.com/aws/aws-sdk-go-v2/service/s3 v1.67.1
+)

examples/scan-s3obj/go.sum

@@ -0,0 +1,66 @@
+github.com/trendmicro/tm-v1-fs-golang-sdk v0.0.0-20241119105152-8e5832d37e21 h1:30XGBlE8B4nrYGFPNxz8Q+tIPQPb95zKIHqmVM5jh8w=
+github.com/trendmicro/tm-v1-fs-golang-sdk v0.0.0-20241119105152-8e5832d37e21/go.mod h1:P/bveu/shq7hy5xRt2h6L1H6yR2FGqaNIJ7lm+yJLKU=
+github.com/aws/aws-sdk-go-v2 v1.32.5 h1:U8vdWJuY7ruAkzaOdD7guwJjD06YSKmnKCJs7s3IkIo=
+github.com/aws/aws-sdk-go-v2 v1.32.5/go.mod h1:P5WJBrYqqbWVaOxgH0X/FYYD47/nooaPOZPlQdmiN2U=
+github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.6.7 h1:lL7IfaFzngfx0ZwUGOZdsFFnQ5uLvR0hWqqhyE7Q9M8=
+github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.6.7/go.mod h1:QraP0UcVlQJsmHfioCrveWOC1nbiWUl3ej08h4mXWoc=
+github.com/aws/aws-sdk-go-v2/config v1.28.5 h1:Za41twdCXbuyyWv9LndXxZZv3QhTG1DinqlFsSuvtI0=
+github.com/aws/aws-sdk-go-v2/config v1.28.5/go.mod h1:4VsPbHP8JdcdUDmbTVgNL/8w9SqOkM5jyY8ljIxLO3o=
+github.com/aws/aws-sdk-go-v2/credentials v1.17.46 h1:AU7RcriIo2lXjUfHFnFKYsLCwgbz1E7Mm95ieIRDNUg=
+github.com/aws/aws-sdk-go-v2/credentials v1.17.46/go.mod h1:1FmYyLGL08KQXQ6mcTlifyFXfJVCNJTVGuQP4m0d/UA=
+github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.16.20 h1:sDSXIrlsFSFJtWKLQS4PUWRvrT580rrnuLydJrCQ/yA=
+github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.16.20/go.mod h1:WZ/c+w0ofps+/OUqMwWgnfrgzZH1DZO1RIkktICsqnY=
+github.com/aws/aws-sdk-go-v2/internal/configsources v1.3.24 h1:4usbeaes3yJnCFC7kfeyhkdkPtoRYPa/hTmCqMpKpLI=
+github.com/aws/aws-sdk-go-v2/internal/configsources v1.3.24/go.mod h1:5CI1JemjVwde8m2WG3cz23qHKPOxbpkq0HaoreEgLIY=
+github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.6.24 h1:N1zsICrQglfzaBnrfM0Ys00860C+QFwu6u/5+LomP+o=
+github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.6.24/go.mod h1:dCn9HbJ8+K31i8IQ8EWmWj0EiIk0+vKiHNMxTTYveAg=
+github.com/aws/aws-sdk-go-v2/internal/ini v1.8.1 h1:VaRN3TlFdd6KxX1x3ILT5ynH6HvKgqdiXoTxAF4HQcQ=
+github.com/aws/aws-sdk-go-v2/internal/ini v1.8.1/go.mod h1:FbtygfRFze9usAadmnGJNc8KsP346kEe+y2/oyhGAGc=
+github.com/aws/aws-sdk-go-v2/internal/v4a v1.3.24 h1:JX70yGKLj25+lMC5Yyh8wBtvB01GDilyRuJvXJ4piD0=
+github.com/aws/aws-sdk-go-v2/internal/v4a v1.3.24/go.mod h1:+Ln60j9SUTD0LEwnhEB0Xhg61DHqplBrbZpLgyjoEHg=
+github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.12.1 h1:iXtILhvDxB6kPvEXgsDhGaZCSC6LQET5ZHSdJozeI0Y=
+github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.12.1/go.mod h1:9nu0fVANtYiAePIBh2/pFUSwtJ402hLnp854CNoDOeE=
+github.com/aws/aws-sdk-go-v2/service/internal/checksum v1.4.5 h1:gvZOjQKPxFXy1ft3QnEyXmT+IqneM9QAUWlM3r0mfqw=
+github.com/aws/aws-sdk-go-v2/service/internal/checksum v1.4.5/go.mod h1:DLWnfvIcm9IET/mmjdxeXbBKmTCm0ZB8p1za9BVteM8=
+github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.12.5 h1:wtpJ4zcwrSbwhECWQoI/g6WM9zqCcSpHDJIWSbMLOu4=
+github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.12.5/go.mod h1:qu/W9HXQbbQ4+1+JcZp0ZNPV31ym537ZJN+fiS7Ti8E=
+github.com/aws/aws-sdk-go-v2/service/internal/s3shared v1.18.5 h1:P1doBzv5VEg1ONxnJss1Kh5ZG/ewoIE4MQtKKc6Crgg=
+github.com/aws/aws-sdk-go-v2/service/internal/s3shared v1.18.5/go.mod h1:NOP+euMW7W3Ukt28tAxPuoWao4rhhqJD3QEBk7oCg7w=
+github.com/aws/aws-sdk-go-v2/service/s3 v1.67.1 h1:LXLnDfjT/P6SPIaCE86xCOjJROPn4FNB2EdN68vMK5c=
+github.com/aws/aws-sdk-go-v2/service/s3 v1.67.1/go.mod h1:ralv4XawHjEMaHOWnTFushl0WRqim/gQWesAMF6hTow=
+github.com/aws/aws-sdk-go-v2/service/sso v1.24.6 h1:3zu537oLmsPfDMyjnUS2g+F2vITgy5pB74tHI+JBNoM=
+github.com/aws/aws-sdk-go-v2/service/sso v1.24.6/go.mod h1:WJSZH2ZvepM6t6jwu4w/Z45Eoi75lPN7DcydSRtJg6Y=
+github.com/aws/aws-sdk-go-v2/service/ssooidc v1.28.5 h1:K0OQAsDywb0ltlFrZm0JHPY3yZp/S9OaoLU33S7vPS8=
+github.com/aws/aws-sdk-go-v2/service/ssooidc v1.28.5/go.mod h1:ORITg+fyuMoeiQFiVGoqB3OydVTLkClw/ljbblMq6Cc=
+github.com/aws/aws-sdk-go-v2/service/sts v1.33.1 h1:6SZUVRQNvExYlMLbHdlKB48x0fLbc2iVROyaNEwBHbU=
+github.com/aws/aws-sdk-go-v2/service/sts v1.33.1/go.mod h1:GqWyYCwLXnlUB1lOAXQyNSPqPLQJvmo8J0DWBzp9mtg=
+github.com/aws/smithy-go v1.22.1 h1:/HPHZQ0g7f4eUeK6HKglFz8uwVfZKgoI25rb/J+dnro=
+github.com/aws/smithy-go v1.22.1/go.mod h1:irrKGvNn1InZwb2d7fkIRNucdfwR8R+Ts3wxYa/cJHg=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/golang-jwt/jwt v3.2.2+incompatible h1:IfV12K8xAKAnZqdXVzCZ+TOjboZ2keLg81eXfW3O+oY=
+github.com/golang-jwt/jwt v3.2.2+incompatible/go.mod h1:8pz2t5EyA70fFQQSrl6XZXzqecmYZeUEB8OUGHkxJ+I=
+github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek=
+github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps=
+github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
+github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/testify v1.8.1 h1:w7B6lhMri9wdJUVmEZPGGhZzrYTPvgJArz7wNPgYKsk=
+github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
+golang.org/x/exp v0.0.0-20231006140011-7918f672742d h1:jtJma62tbqLibJ5sFQz8bKtEM8rJBtfilJ2qTU199MI=
+golang.org/x/exp v0.0.0-20231006140011-7918f672742d/go.mod h1:ldy0pHrwJyGW56pPQzzkH36rKxoZW1tw7ZJpeKx+hdo=
+golang.org/x/net v0.22.0 h1:9sGLhx7iRIHEiX0oAJ3MRZMUCElJgy7Br1nO+AMN3Tc=
+golang.org/x/net v0.22.0/go.mod h1:JKghWKKOSdJwpW2GEx0Ja7fmaKnMsbu+MWVZTokSYmg=
+golang.org/x/sys v0.18.0 h1:DBdB3niSjOA/O0blCZBqDefyWNYveAYMNF1Wum0DYQ4=
+golang.org/x/sys v0.18.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+golang.org/x/text v0.14.0 h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ=
+golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20240311173647-c811ad7063a7 h1:8EeVk1VKMD+GD/neyEHGmz7pFblqPjHoi+PGQIlLx2s=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20240311173647-c811ad7063a7/go.mod h1:WtryC6hu0hhx87FDGxWCDptyssuo68sk10vYjF+T9fY=
+google.golang.org/grpc v1.62.1 h1:B4n+nfKzOICUXMgyrNd19h/I9oH0L1pizfk1d4zSgTk=
+google.golang.org/grpc v1.62.1/go.mod h1:IWTG0VlJLCh1SkC58F7np9ka9mx/WNkjl4PGJaiq+QE=
+google.golang.org/protobuf v1.33.0 h1:uNO2rsAINq/JlFpSdYEKIZ0uKD/R9cpdv0T+yoGwGmI=
+google.golang.org/protobuf v1.33.0/go.mod h1:c6P6GXX6sHbq/GpV6MGZEdwhWPcYBgnhAHhKbcUYpos=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

examples/scan-s3obj/scan-s3obj.go

@@ -0,0 +1,183 @@
+package main
+
+/*
+This is an example of a test program that can execute a scan on a HTTP URL.
+It will return an array of AMaaS scan results as part of its JSON output.
+*/
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"io"
+	"log"
+	"os"
+	"strings"
+
+	amaasclient "github.com/trendmicro/tm-v1-fs-golang-sdk"
+
+	"github.com/aws/aws-sdk-go-v2/config"
+	"github.com/aws/aws-sdk-go-v2/service/s3"
+	"github.com/aws/aws-sdk-go-v2/service/s3/types"
+)
+
+func main() {
+
+	var bucketregion string
+	var bucket string
+	var key string
+
+	var grpcAddr string
+	var apiKey string
+	var tls bool
+	var caCert string
+	var region string
+	var pml bool
+	var feedback bool
+	var verbose bool
+	var tag string
+	var digest bool
+
+	flag.StringVar(&bucketregion, "bucketregion", "us-west-2", "region for S3 bucket")
+	flag.StringVar(&bucket, "bucket", "", "S3 bucket name")
+	flag.StringVar(&key, "key", "", "S3 object key")
+
+	flag.StringVar(&grpcAddr, "addr", "", "the address to connect to for GRPC")
+	flag.StringVar(&apiKey, "apikey", "", "API key for service authentication")
+	flag.BoolVar(&tls, "tls", false, "enable server TLS by client for GRPC.")
+	flag.StringVar(&region, "region", "", "the region to connect to")
+	flag.BoolVar(&pml, "pml", false, "enable predictive machine learning detection")
+	flag.BoolVar(&feedback, "feedback", false, "enable SPN feedback")
+	flag.BoolVar(&verbose, "verbose", false, "enable verbose scan result")
+	flag.StringVar(&tag, "tag", "", "tags to be used for scanning. separated by comma.")
+	flag.StringVar(&caCert, "ca_cert", "", "CA certificate for self hosted AMaaS server")
+	flag.BoolVar(&digest, "digest", false, "enable digest calculation. it might increase network traffic for cloud file.")
+
+	flag.Parse()
+
+	var ac *amaasclient.AmaasClient
+	var err error
+
+	if region != "" && grpcAddr != "" {
+		log.Fatal("Both region and addr are specified. Please specify only one.")
+	} else if region != "" {
+		ac, err = amaasclient.NewClient(apiKey, region)
+		if err != nil {
+			log.Fatalf("Unable to create AMaaS scan client object. error: %v", err)
+		}
+	} else if grpcAddr != "" {
+		ac, err = amaasclient.NewClientInternal(apiKey, grpcAddr, tls, caCert)
+		if err != nil {
+			log.Fatalf("Unable to create AMaaS scan client object. error: %v", err)
+		}
+	} else {
+		log.Fatal("Neither region nor addr is specified. Please specify one.")
+	}
+
+	if pml {
+		ac.SetPMLEnable()
+	}
+
+	if feedback {
+		ac.SetFeedbackEnable()
+	}
+
+	if verbose {
+		ac.SetVerboseEnable()
+	}
+
+	if !digest {
+		// disable digest calculation to reduce network traffic if file is on cloud
+		ac.SetDigestDisable()
+	}
+
+	var tagsArray []string
+	if tag != "" {
+		tagsArray = strings.Split(tag, ",")
+	}
+
+	reader, err := NewS3ClientReader(context.Background(), bucketregion, bucket, key)
+	if err != nil {
+		log.Fatalf("Unable to create S3 client reader. error: %v", err)
+	}
+
+	result, err := ac.ScanReader(reader, tagsArray)
+	if err != nil {
+		log.Fatalf("Unable to scan reader. error: %v", err)
+	}
+
+	fmt.Printf("%v", result)
+
+	os.Exit(0)
+}
+
+type S3ClientReader struct {
+	client *s3.Client
+	bucket string
+	key    string
+	size   int64
+}
+
+func NewS3ClientReader(ctx context.Context, bucketregion, bucket, key string) (*S3ClientReader, error) {
+	// load default config from environment with specified region
+	cfg, err := config.LoadDefaultConfig(ctx, config.WithRegion(bucketregion))
+	if err != nil {
+		return nil, err
+	}
+	defer ctx.Done()
+
+	// create S3 client with given config
+	client := s3.NewFromConfig(cfg)
+
+	attr, err := client.GetObjectAttributes(ctx, &s3.GetObjectAttributesInput{
+		Bucket: &bucket,
+		Key:    &key,
+		ObjectAttributes: []types.ObjectAttributes{
+			types.ObjectAttributesObjectSize,
+		},
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	if attr.ObjectSize == nil {
+		return nil, fmt.Errorf("unable to get object size from S3")
+	}
+
+	return &S3ClientReader{
+		client: client,
+		bucket: bucket,
+		key:    key,
+		size:   *attr.ObjectSize,
+	}, nil
+}
+
+// S3ClientReader implements AmaasClientReader
+func (r *S3ClientReader) Identifier() string {
+	return fmt.Sprintf("s3://%s/%s", r.bucket, r.key)
+}
+
+func (r *S3ClientReader) DataSize() (int64, error) {
+	return r.size, nil
+}
+
+func (r *S3ClientReader) ReadBytes(offset int64, length int32) ([]byte, error) {
+	var rng string = fmt.Sprintf("bytes=%d-%d", offset, offset+int64(length)-1)
+
+	output, err := r.client.GetObject(context.Background(), &s3.GetObjectInput{
+		Bucket: &r.bucket,
+		Key:    &r.key,
+		Range:  &rng,
+	})
+	if err != nil {
+		return nil, err
+	}
+	defer output.Body.Close()
+
+	bytes, err := io.ReadAll(output.Body)
+	if err != nil && err != io.EOF {
+		bytes = nil
+	}
+
+	return bytes, err
+}