1 // Copyright 2024 Google LLC. 2 // Use of this source code is governed by a BSD-style 3 // license that can be found in the LICENSE file. 4 5 // Code generated file. DO NOT EDIT. 6 7 // Package safebrowsing provides access to the Safe Browsing API. 8 // 9 // For product documentation, see: https://developers.google.com/safe-browsing/ 10 // 11 // # Library status 12 // 13 // These client libraries are officially supported by Google. However, this 14 // library is considered complete and is in maintenance mode. This means 15 // that we will address critical bugs and security issues but will not add 16 // any new features. 17 // 18 // When possible, we recommend using our newer 19 // [Cloud Client Libraries for Go](https://pkg.go.dev/cloud.google.com/go) 20 // that are still actively being worked and iterated on. 21 // 22 // # Creating a client 23 // 24 // Usage example: 25 // 26 // import "google.golang.org/api/safebrowsing/v5" 27 // ... 28 // ctx := context.Background() 29 // safebrowsingService, err := safebrowsing.NewService(ctx) 30 // 31 // In this example, Google Application Default Credentials are used for 32 // authentication. For information on how to create and obtain Application 33 // Default Credentials, see https://developers.google.com/identity/protocols/application-default-credentials. 34 // 35 // # Other authentication options 36 // 37 // To use an API key for authentication (note: some APIs do not support API 38 // keys), use [google.golang.org/api/option.WithAPIKey]: 39 // 40 // safebrowsingService, err := safebrowsing.NewService(ctx, option.WithAPIKey("AIza...")) 41 // 42 // To use an OAuth token (e.g., a user token obtained via a three-legged OAuth 43 // flow, use [google.golang.org/api/option.WithTokenSource]: 44 // 45 // config := &oauth2.Config{...} 46 // // ... 47 // token, err := config.Exchange(ctx, ...) 48 // safebrowsingService, err := safebrowsing.NewService(ctx, option.WithTokenSource(config.TokenSource(ctx, token))) 49 // 50 // See [google.golang.org/api/option.ClientOption] for details on options. 51 package safebrowsing // import "google.golang.org/api/safebrowsing/v5" 52 53 import ( 54 "bytes" 55 "context" 56 "encoding/json" 57 "errors" 58 "fmt" 59 "io" 60 "net/http" 61 "net/url" 62 "strconv" 63 "strings" 64 65 googleapi "google.golang.org/api/googleapi" 66 internal "google.golang.org/api/internal" 67 gensupport "google.golang.org/api/internal/gensupport" 68 option "google.golang.org/api/option" 69 internaloption "google.golang.org/api/option/internaloption" 70 htransport "google.golang.org/api/transport/http" 71 ) 72 73 // Always reference these packages, just in case the auto-generated code 74 // below doesn't. 75 var _ = bytes.NewBuffer 76 var _ = strconv.Itoa 77 var _ = fmt.Sprintf 78 var _ = json.NewDecoder 79 var _ = io.Copy 80 var _ = url.Parse 81 var _ = gensupport.MarshalJSON 82 var _ = googleapi.Version 83 var _ = errors.New 84 var _ = strings.Replace 85 var _ = context.Canceled 86 var _ = internaloption.WithDefaultEndpoint 87 var _ = internal.Version 88 89 const apiId = "safebrowsing:v5" 90 const apiName = "safebrowsing" 91 const apiVersion = "v5" 92 const basePath = "https://safebrowsing.googleapis.com/" 93 const basePathTemplate = "https://safebrowsing.UNIVERSE_DOMAIN/" 94 const mtlsBasePath = "https://safebrowsing.mtls.googleapis.com/" 95 96 // NewService creates a new Service. 97 func NewService(ctx context.Context, opts ...option.ClientOption) (*Service, error) { 98 opts = append(opts, internaloption.WithDefaultEndpoint(basePath)) 99 opts = append(opts, internaloption.WithDefaultEndpointTemplate(basePathTemplate)) 100 opts = append(opts, internaloption.WithDefaultMTLSEndpoint(mtlsBasePath)) 101 opts = append(opts, internaloption.EnableNewAuthLibrary()) 102 client, endpoint, err := htransport.NewClient(ctx, opts...) 103 if err != nil { 104 return nil, err 105 } 106 s, err := New(client) 107 if err != nil { 108 return nil, err 109 } 110 if endpoint != "" { 111 s.BasePath = endpoint 112 } 113 return s, nil 114 } 115 116 // New creates a new Service. It uses the provided http.Client for requests. 117 // 118 // Deprecated: please use NewService instead. 119 // To provide a custom HTTP client, use option.WithHTTPClient. 120 // If you are using google.golang.org/api/googleapis/transport.APIKey, use option.WithAPIKey with NewService instead. 121 func New(client *http.Client) (*Service, error) { 122 if client == nil { 123 return nil, errors.New("client is nil") 124 } 125 s := &Service{client: client, BasePath: basePath} 126 s.Hashes = NewHashesService(s) 127 return s, nil 128 } 129 130 type Service struct { 131 client *http.Client 132 BasePath string // API endpoint base URL 133 UserAgent string // optional additional User-Agent fragment 134 135 Hashes *HashesService 136 } 137 138 func (s *Service) userAgent() string { 139 if s.UserAgent == "" { 140 return googleapi.UserAgent 141 } 142 return googleapi.UserAgent + " " + s.UserAgent 143 } 144 145 func NewHashesService(s *Service) *HashesService { 146 rs := &HashesService{s: s} 147 return rs 148 } 149 150 type HashesService struct { 151 s *Service 152 } 153 154 // GoogleSecuritySafebrowsingV5FullHash: The full hash identified with one or 155 // more matches. 156 type GoogleSecuritySafebrowsingV5FullHash struct { 157 // FullHash: The matching full hash. This is the SHA256 hash. The length will 158 // be exactly 32 bytes. 159 FullHash string `json:"fullHash,omitempty"` 160 // FullHashDetails: Unordered list. A repeated field identifying the details 161 // relevant to this full hash. 162 FullHashDetails []*GoogleSecuritySafebrowsingV5FullHashFullHashDetail `json:"fullHashDetails,omitempty"` 163 // ForceSendFields is a list of field names (e.g. "FullHash") to 164 // unconditionally include in API requests. By default, fields with empty or 165 // default values are omitted from API requests. See 166 // https://pkg.go.dev/google.golang.org/api#hdr-ForceSendFields for more 167 // details. 168 ForceSendFields []string `json:"-"` 169 // NullFields is a list of field names (e.g. "FullHash") to include in API 170 // requests with the JSON null value. By default, fields with empty values are 171 // omitted from API requests. See 172 // https://pkg.go.dev/google.golang.org/api#hdr-NullFields for more details. 173 NullFields []string `json:"-"` 174 } 175 176 func (s *GoogleSecuritySafebrowsingV5FullHash) MarshalJSON() ([]byte, error) { 177 type NoMethod GoogleSecuritySafebrowsingV5FullHash 178 return gensupport.MarshalJSON(NoMethod(*s), s.ForceSendFields, s.NullFields) 179 } 180 181 // GoogleSecuritySafebrowsingV5FullHashFullHashDetail: Details about a matching 182 // full hash. An important note about forward compatibility: new threat types 183 // and threat attributes may be added by the server at any time; those 184 // additions are considered minor version changes. It is Google's policy not to 185 // expose minor version numbers in APIs (see 186 // https://cloud.google.com/apis/design/versioning for the versioning policy), 187 // so clients MUST be prepared to receive `FullHashDetail` messages containing 188 // `ThreatType` enum values or `ThreatAttribute` enum values that are 189 // considered invalid by the client. Therefore, it is the client's 190 // responsibility to check for the validity of all `ThreatType` and 191 // `ThreatAttribute` enum values; if any value is considered invalid, the 192 // client MUST disregard the entire `FullHashDetail` message. 193 type GoogleSecuritySafebrowsingV5FullHashFullHashDetail struct { 194 // Attributes: Unordered list. Additional attributes about those full hashes. 195 // This may be empty. 196 // 197 // Possible values: 198 // "THREAT_ATTRIBUTE_UNSPECIFIED" - Unknown attribute. If this is returned by 199 // the server, the client shall disregard the enclosing `FullHashDetail` 200 // altogether. 201 // "CANARY" - Indicates that the threat_type should not be used for 202 // enforcement. 203 // "FRAME_ONLY" - Indicates that the threat_type should only be used for 204 // enforcement on frames. 205 Attributes []string `json:"attributes,omitempty"` 206 // ThreatType: The type of threat. This field will never be empty. 207 // 208 // Possible values: 209 // "THREAT_TYPE_UNSPECIFIED" - Unknown threat type. If this is returned by 210 // the server, the client shall disregard the enclosing `FullHashDetail` 211 // altogether. 212 // "MALWARE" - Malware threat type. Malware is any software or mobile 213 // application specifically designed to harm a computer, a mobile device, the 214 // software it's running, or its users. Malware exhibits malicious behavior 215 // that can include installing software without user consent and installing 216 // harmful software such as viruses. More information can be found 217 // [here](https://developers.google.com/search/docs/monitor-debug/security/malwa 218 // re). 219 // "SOCIAL_ENGINEERING" - Social engineering threat type. Social engineering 220 // pages falsely purport to act on behalf of a third party with the intention 221 // of confusing viewers into performing an action with which the viewer would 222 // only trust a true agent of that third party. Phishing is a type of social 223 // engineering that tricks the viewer into performing the specific action of 224 // providing information, such as login credentials. More information can be 225 // found 226 // [here](https://developers.google.com/search/docs/monitor-debug/security/socia 227 // l-engineering). 228 // "UNWANTED_SOFTWARE" - Unwanted software threat type. Unwanted software is 229 // any software that does not adhere to [Google's Software 230 // Principles](https://www.google.com/about/software-principles.html) but isn't 231 // malware. 232 // "POTENTIALLY_HARMFUL_APPLICATION" - Potentially harmful application threat 233 // type [as used by Google Play Protect for the Play 234 // Store](https://developers.google.com/android/play-protect/potentially-harmful 235 // -applications). 236 ThreatType string `json:"threatType,omitempty"` 237 // ForceSendFields is a list of field names (e.g. "Attributes") to 238 // unconditionally include in API requests. By default, fields with empty or 239 // default values are omitted from API requests. See 240 // https://pkg.go.dev/google.golang.org/api#hdr-ForceSendFields for more 241 // details. 242 ForceSendFields []string `json:"-"` 243 // NullFields is a list of field names (e.g. "Attributes") to include in API 244 // requests with the JSON null value. By default, fields with empty values are 245 // omitted from API requests. See 246 // https://pkg.go.dev/google.golang.org/api#hdr-NullFields for more details. 247 NullFields []string `json:"-"` 248 } 249 250 func (s *GoogleSecuritySafebrowsingV5FullHashFullHashDetail) MarshalJSON() ([]byte, error) { 251 type NoMethod GoogleSecuritySafebrowsingV5FullHashFullHashDetail 252 return gensupport.MarshalJSON(NoMethod(*s), s.ForceSendFields, s.NullFields) 253 } 254 255 // GoogleSecuritySafebrowsingV5SearchHashesResponse: The response returned 256 // after searching threat hashes. If nothing is found, the server will return 257 // an OK status (HTTP status code 200) with the `full_hashes` field empty, 258 // rather than returning a NOT_FOUND status (HTTP status code 404). **What's 259 // new in V5**: There is a separation between `FullHash` and `FullHashDetail`. 260 // In the case when a hash represents a site having multiple threats (e.g. both 261 // MALWARE and SOCIAL_ENGINEERING), the full hash does not need to be sent 262 // twice as in V4. Furthermore, the cache duration has been simplified into a 263 // single `cache_duration` field. 264 type GoogleSecuritySafebrowsingV5SearchHashesResponse struct { 265 // CacheDuration: The client-side cache duration. The client MUST add this 266 // duration to the current time to determine the expiration time. The 267 // expiration time then applies to every hash prefix queried by the client in 268 // the request, regardless of how many full hashes are returned in the 269 // response. Even if the server returns no full hashes for a particular hash 270 // prefix, this fact MUST also be cached by the client. If and only if the 271 // field `full_hashes` is empty, the client MAY increase the `cache_duration` 272 // to determine a new expiration that is later than that specified by the 273 // server. In any case, the increased cache duration must not be longer than 24 274 // hours. Important: the client MUST NOT assume that the server will return the 275 // same cache duration for all responses. The server MAY choose different cache 276 // durations for different responses depending on the situation. 277 CacheDuration string `json:"cacheDuration,omitempty"` 278 // FullHashes: Unordered list. The unordered list of full hashes found. 279 FullHashes []*GoogleSecuritySafebrowsingV5FullHash `json:"fullHashes,omitempty"` 280 281 // ServerResponse contains the HTTP response code and headers from the server. 282 googleapi.ServerResponse `json:"-"` 283 // ForceSendFields is a list of field names (e.g. "CacheDuration") to 284 // unconditionally include in API requests. By default, fields with empty or 285 // default values are omitted from API requests. See 286 // https://pkg.go.dev/google.golang.org/api#hdr-ForceSendFields for more 287 // details. 288 ForceSendFields []string `json:"-"` 289 // NullFields is a list of field names (e.g. "CacheDuration") to include in API 290 // requests with the JSON null value. By default, fields with empty values are 291 // omitted from API requests. See 292 // https://pkg.go.dev/google.golang.org/api#hdr-NullFields for more details. 293 NullFields []string `json:"-"` 294 } 295 296 func (s *GoogleSecuritySafebrowsingV5SearchHashesResponse) MarshalJSON() ([]byte, error) { 297 type NoMethod GoogleSecuritySafebrowsingV5SearchHashesResponse 298 return gensupport.MarshalJSON(NoMethod(*s), s.ForceSendFields, s.NullFields) 299 } 300 301 type HashesSearchCall struct { 302 s *Service 303 urlParams_ gensupport.URLParams 304 ifNoneMatch_ string 305 ctx_ context.Context 306 header_ http.Header 307 } 308 309 // Search: Search for full hashes matching the specified prefixes. This is a 310 // custom method as defined by https://google.aip.dev/136 (the custom method 311 // refers to this method having a custom name within Google's general API 312 // development nomenclature; it does not refer to using a custom HTTP method). 313 func (r *HashesService) Search() *HashesSearchCall { 314 c := &HashesSearchCall{s: r.s, urlParams_: make(gensupport.URLParams)} 315 return c 316 } 317 318 // HashPrefixes sets the optional parameter "hashPrefixes": Required. The hash 319 // prefixes to be looked up. Clients MUST NOT send more than 1000 hash 320 // prefixes. However, following the URL processing procedure, clients SHOULD 321 // NOT need to send more than 30 hash prefixes. Currently each hash prefix is 322 // required to be exactly 4 bytes long. This MAY be relaxed in the future. 323 func (c *HashesSearchCall) HashPrefixes(hashPrefixes ...string) *HashesSearchCall { 324 c.urlParams_.SetMulti("hashPrefixes", append([]string{}, hashPrefixes...)) 325 return c 326 } 327 328 // Fields allows partial responses to be retrieved. See 329 // https://developers.google.com/gdata/docs/2.0/basics#PartialResponse for more 330 // details. 331 func (c *HashesSearchCall) Fields(s ...googleapi.Field) *HashesSearchCall { 332 c.urlParams_.Set("fields", googleapi.CombineFields(s)) 333 return c 334 } 335 336 // IfNoneMatch sets an optional parameter which makes the operation fail if the 337 // object's ETag matches the given value. This is useful for getting updates 338 // only after the object has changed since the last request. 339 func (c *HashesSearchCall) IfNoneMatch(entityTag string) *HashesSearchCall { 340 c.ifNoneMatch_ = entityTag 341 return c 342 } 343 344 // Context sets the context to be used in this call's Do method. 345 func (c *HashesSearchCall) Context(ctx context.Context) *HashesSearchCall { 346 c.ctx_ = ctx 347 return c 348 } 349 350 // Header returns a http.Header that can be modified by the caller to add 351 // headers to the request. 352 func (c *HashesSearchCall) Header() http.Header { 353 if c.header_ == nil { 354 c.header_ = make(http.Header) 355 } 356 return c.header_ 357 } 358 359 func (c *HashesSearchCall) doRequest(alt string) (*http.Response, error) { 360 reqHeaders := gensupport.SetHeaders(c.s.userAgent(), "", c.header_) 361 if c.ifNoneMatch_ != "" { 362 reqHeaders.Set("If-None-Match", c.ifNoneMatch_) 363 } 364 var body io.Reader = nil 365 c.urlParams_.Set("alt", alt) 366 c.urlParams_.Set("prettyPrint", "false") 367 urls := googleapi.ResolveRelative(c.s.BasePath, "v5/hashes:search") 368 urls += "?" + c.urlParams_.Encode() 369 req, err := http.NewRequest("GET", urls, body) 370 if err != nil { 371 return nil, err 372 } 373 req.Header = reqHeaders 374 return gensupport.SendRequest(c.ctx_, c.s.client, req) 375 } 376 377 // Do executes the "safebrowsing.hashes.search" call. 378 // Any non-2xx status code is an error. Response headers are in either 379 // *GoogleSecuritySafebrowsingV5SearchHashesResponse.ServerResponse.Header or 380 // (if a response was returned at all) in error.(*googleapi.Error).Header. Use 381 // googleapi.IsNotModified to check whether the returned error was because 382 // http.StatusNotModified was returned. 383 func (c *HashesSearchCall) Do(opts ...googleapi.CallOption) (*GoogleSecuritySafebrowsingV5SearchHashesResponse, error) { 384 gensupport.SetOptions(c.urlParams_, opts...) 385 res, err := c.doRequest("json") 386 if res != nil && res.StatusCode == http.StatusNotModified { 387 if res.Body != nil { 388 res.Body.Close() 389 } 390 return nil, gensupport.WrapError(&googleapi.Error{ 391 Code: res.StatusCode, 392 Header: res.Header, 393 }) 394 } 395 if err != nil { 396 return nil, err 397 } 398 defer googleapi.CloseBody(res) 399 if err := googleapi.CheckResponse(res); err != nil { 400 return nil, gensupport.WrapError(err) 401 } 402 ret := &GoogleSecuritySafebrowsingV5SearchHashesResponse{ 403 ServerResponse: googleapi.ServerResponse{ 404 Header: res.Header, 405 HTTPStatusCode: res.StatusCode, 406 }, 407 } 408 target := &ret 409 if err := gensupport.DecodeResponse(target, res); err != nil { 410 return nil, err 411 } 412 return ret, nil 413 } 414