passivetotalx 0.1.0

data/lib/passivetotal/clients/artifact.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module PassiveTotal
+  module Client
+    class Artifact < Base
+      #
+      # Create artifacts in bulk.
+      # http://api.passivetotal.org/api/docs/#api-Artifact-PutV2ArtifactBulk
+      #
+      # @param [Array<Hash>] artifacts a list of dictionaries that match the /v2/artifact interface (has query, type, tags, and project fields per dictionary)
+      #
+      # @return [Hash]
+      #
+      def bulk_create(artifacts)
+        params = {
+          artifacts: artifacts,
+        }.compact
+
+        _put("/artifact/bulk", params) { |json| json }
+      end
+
+      #
+      # Delete artifacts in bulk.
+      # http://api.passivetotal.org/api/docs/#api-Artifact-DeleteV2ArtifactBulk
+      #
+      # @param [Array<String>] artifacts the artifact ids to delete
+      #
+      # @return [Hash]
+      #
+      def bulk_delete(artifacts)
+        params = {
+          artifacts: artifacts,
+        }.compact
+
+        _delete("/artifact/bulk", params) { |json| json }
+      end
+
+      #
+      # Perform artifact updates in bulk.
+      # http://api.passivetotal.org/api/docs/#api-Artifact-PostV2ArtifactBulk
+      #
+      # @param [Array<Hash>] artifacts a list of dictionaries which match the fields for the /v2/artifact (artifact, monitor, tags)
+      #
+      # @return [Hash]
+      #
+      def bulk_update(artifacts)
+        params = {
+          artifacts: artifacts,
+        }.compact
+
+        _post("/artifact/bulk", params) { |json| json }
+      end
+
+      #
+      # Create an artifact.
+      # http://api.passivetotal.org/api/docs/#api-Artifact-PutV2Artifact
+      #
+      # @param [String] project the project id the artifact will live on
+      # @param [String] query the actual artifact query (passivetotal.org, 8.8.8.8, etc).
+      # @param [String, nil] type the type of the artifact (domain, ip, etc), or inferred by query string if domain or ip (optional).
+      # @param [String, nil] tags the tags the new artifact will have
+      #
+      # @return [Hash]
+      #
+      def create(project:, query:, type: nil, tags: nil)
+        params = {
+          project: project,
+          query: query,
+          type: type,
+          tags: tags,
+        }.compact
+
+        _put("/artifact", params) { |json| json }
+      end
+
+      #
+      # Delete an artifact with a UUID.
+      # http://api.passivetotal.org/api/docs/#api-Artifact-DeleteV2Artifact
+      #
+      # @param [String] artifact the artifact id
+      #
+      # @return [Hash]
+      #
+      def delete(artifact)
+        params = {
+          artifact: artifact,
+        }.compact
+
+        _delete("/artifact", params) { |json| json }
+      end
+
+      #
+      # Read existing artifacts. If no filters are passed, this returns all your personal artifacts created by you or your organization.
+      # http://api.passivetotal.org/api/docs/#api-Artifact-GetV2Artifact
+      #
+      # @param [String] artifact the artifact id
+      # @param [String] project filter by project id
+      # @param [String] owner filter by owner (an email or organization id)
+      # @param [String] creator filter by creator
+      # @param [String] organization filter by organization
+      # @param [String] query filter by query (passivetotal.org, etc)
+      # @param [String] type filter by artifact type (domain, ip, etc)
+      #
+      # @return [Hash]
+      #
+      def find(artifact: nil, project: nil, owner: nil, creator: nil, organization: nil, query: nil, type: nil)
+        params = {
+          artifact: artifact,
+          project: project,
+          owner: owner,
+          creator: creator,
+          organization: organization,
+          query: query,
+          type: type,
+        }.compact
+
+        _get("/artifact", params) { |json| json }
+      end
+
+      #
+      # Update artifact, or toggle monitoring status. If you want to change the query or artifact type, simply delete it and create a new one. Use /v2/artifact/tag to add or delete tags without setting everything at once.
+      # http://api.passivetotal.org/api/docs/#api-Artifact-PostV2Artifact
+      #
+      # @param [String] artifact the artifact id to update
+      # @param [String, nil] monitor whether to monitor the artifact
+      # @param [Array<String>, nil] tags sets the artifact's tags to this list
+      #
+      # @return [Hash]
+      #
+      def update(artifact, monitor: nil, tags: nil)
+        params = {
+          artifact: artifact,
+          monitor: monitor,
+          tags: tags,
+        }.compact
+
+        _post("/artifact", params) { |json| json }
+      end
+    end
+  end
+end

data/lib/passivetotal/clients/base.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module PassiveTotal
+  module Client
+    class Base
+      HOST = "api.passivetotal.org"
+      VERSION = "v2"
+      BASE_URL = "https://#{HOST}/#{VERSION}"
+
+      def initialize(username:, api_key:)
+        @username = username
+        @api_key = api_key
+      end
+
+      private
+
+      def url_for(path)
+        URI(BASE_URL + path)
+      end
+
+      def https_options
+        if proxy = ENV["HTTPS_PROXY"] || ENV["https_proxy"]
+          uri = URI(proxy)
+          {
+            proxy_address: uri.hostname,
+            proxy_port: uri.port,
+            proxy_from_env: false,
+            use_ssl: true
+          }
+        else
+          { use_ssl: true }
+        end
+      end
+
+      def make_request(req)
+        Net::HTTP.start(HOST, 443, https_options) do |http|
+          response = http.request(req)
+
+          code = response.code.to_i
+          body = response.body
+          json = JSON.parse(body)
+
+          case code
+          when 200
+            yield json
+          else
+            error = json.dig("error") || body
+            raise Error, "Unsupported response code returned: #{code} - #{error}"
+          end
+        end
+      end
+
+      def build_request(type: "GET", path:, params: {})
+        uri = url_for(path)
+        uri.query = URI.encode_www_form(params) if type == "GET"
+
+        request = case type
+                  when "GET"
+                    Net::HTTP::Get.new(uri)
+                  when "POST"
+                    Net::HTTP::Post.new(uri)
+                  when "PUT"
+                    Net::HTTP::Put.new(path)
+                  when "DELETE"
+                    Net::HTTP::Delete.new(path)
+                  else
+                    raise ArgumentError, "#{type} HTTP method is not supported"
+                  end
+
+        request.body = JSON.generate(params) unless type == "GET"
+        request.basic_auth @username, @api_key
+
+        request
+      end
+
+      def _get(path, params = {}, &block)
+        request = build_request(type: "GET", path: path, params: params)
+        make_request(request, &block)
+      end
+
+      def _post(path, params = {}, &block)
+        request = build_request(type: "POST", path: path, params: params)
+        make_request(request, &block)
+      end
+
+      def _put(path, params = {}, &block)
+        request = build_request(type: "PUT", path: path, params: params)
+        make_request(request, &block)
+      end
+
+      def _delete(path, params = {}, &block)
+        request = build_request(type: "DELETE", path: path, params: params)
+        make_request(request, &block)
+      end
+    end
+  end
+end

data/lib/passivetotal/clients/dns.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module PassiveTotal
+  module Client
+    class DNS < Base
+      #
+      # Retrieves the passive DNS results from active account sources.
+      # http://api.passivetotal.org/api/docs/#api-Passive_DNS-GetV2DnsPassive
+      #
+      # @param [String] query the domain or IP being queried
+      # @param [String] start the start datetime
+      # @param [String] end the end datetime
+      # @param [String] timeout timeout to use for external resources
+      #
+      # @return [Hash]
+      #
+      def passive(query, start_at: nil, end_at: nil, timeout: 7)
+        params = {
+          query: query,
+          start: start_at,
+          end: end_at,
+          timeout: timeout,
+        }.compact
+
+        _get("/dns/passive", params) { |json| json }
+      end
+
+      #
+      # Retrieves the unique passive DNS results from active account sources.
+      # http://api.passivetotal.org/api/docs/#api-Passive_DNS-GetV2DnsPassiveUnique
+      #
+      # @param [String] query the domain or IP being queried
+      #
+      # @return [Hash]
+      #
+      def passive_unique(query)
+        params = {
+          query: query,
+        }.compact
+
+        _get("/dns/passive/unique", params) { |json| json }
+      end
+
+      #
+      # Searches the Passive DNS data for a keyword query.
+      # http://api.passivetotal.org/api/docs/#api-Passive_DNS-GetV2DnsSearchKeyword
+      #
+      # @param [String] query query
+      #
+      # @return [Hash]
+      #
+      def search(query)
+        params = {
+          query: query
+        }.compact
+
+        _get("/dns/search/keyword", params) { |json| json }
+      end
+    end
+  end
+end

data/lib/passivetotal/clients/enrichment.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module PassiveTotal
+  module Client
+    class Enrichment < Base
+      #
+      # Get enrichment data for a query
+      # http://api.passivetotal.org/api/docs/#api-Enrichment-GetV2Enrichment
+      #
+      # @param [String] query the domain or IP being queried
+      #
+      # @return [Hash]
+      #
+      def get(query)
+        params = {
+          query: query,
+        }.compact
+
+        _get("/enrichment", params) { |json| json }
+      end
+
+      #
+      # Get malware data for a query
+      # http://api.passivetotal.org/api/docs/#api-Enrichment-GetV2EnrichmentMalware
+      #
+      # @param [String] query the domain or IP being queried
+      #
+      # @return [Hash]
+      #
+      def malware(query)
+        params = {
+          query: query,
+        }.compact
+
+        _get("/enrichment/malware", params) { |json| json }
+      end
+
+      #
+      # Get osint data for a query
+      # http://api.passivetotal.org/api/docs/#api-Enrichment-GetV2EnrichmentOsint
+      #
+      # @param [String] query the domain or IP being queried
+      #
+      # @return [Hash]
+      #
+      def osint(query)
+        params = {
+          query: query,
+        }.compact
+
+        _get("/enrichment/osint", params) { |json| json }
+      end
+
+      #
+      # Get subdomains data for a query
+      # http://api.passivetotal.org/api/docs/#api-Enrichment-GetV2EnrichmentSubdomains
+      #
+      # @param [String] query the domain being queried
+      #
+      # @return [Hash]
+      #
+      def subdomains(query)
+        params = {
+          query: query,
+        }.compact
+
+        _get("/enrichment/subdomains", params) { |json| json }
+      end
+
+      #
+      # Get bulk enrichment data for many queries
+      # http://api.passivetotal.org/api/docs/#api-Bulk_Enrichment-GetV2EnrichmentBulk
+      #
+      # @param [Array<String>] query the domains and IPs being queried
+      #
+      # @return [Hash]
+      #
+      def bulk_data(*query)
+        params = {
+          query: query,
+        }.compact
+
+        _get("/enrichment/bulk", params) { |json| json }
+      end
+
+      #
+      # Get bulk malware data for many queries
+      # http://api.passivetotal.org/api/docs/#api-Bulk_Enrichment-GetV2EnrichmentBulkMalware
+      #
+      # @param [Array<String>] query the domains and IPs being queried
+      #
+      # @return [Hash]
+      #
+      def bulk_malware(*query)
+        params = {
+          query: query,
+        }.compact
+
+        _get("/enrichment/bulk/malware", params) { |json| json }
+      end
+
+      #
+      # Get bulk osint data for many queries
+      # http://api.passivetotal.org/api/docs/#api-Bulk_Enrichment-GetV2EnrichmentBulkOsint
+      #
+      # @param [Array<String>] query the domains and IPs being queried
+      #
+      # @return [Hash]
+      #
+      def bulk_osint(*query)
+        params = {
+          query: query,
+        }.compact
+
+        _get("/enrichment/bulk/osint", params) { |json| json }
+      end
+    end
+  end
+end

data/lib/passivetotal/clients/host.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module PassiveTotal
+  module Client
+    class Host < Base
+      #
+      # Retrieves the host attribute components of a query.
+      # http://api.passivetotal.org/api/docs/#api-Host_Attributes-GetV2HostAttributesComponents
+      #
+      # @param [String] query
+      # @param [String, nil] start_at
+      # @param [String, nil] end_at
+      #
+      # @return [Hash]
+      #
+      def components(query, start_at: nil, end_at: nil)
+        params = {
+          query: query,
+          start: start_at,
+          end: end_at,
+        }.compact
+
+        _get("/host-attributes/components", params) { |json| json }
+      end
+
+      #
+      # Retrieves the host attribute pairs related to the query.
+      # https://api.passivetotal.org/api/docs/#api-Host_Attributes-GetV2HostAttributesComponents
+      #
+      # @param [String] query
+      # @param [String] direction
+      # @param [String] start_at
+      # @param [String] end_at
+      #
+      # @return [Hash]
+      #
+      def pairs(query, direction: "children", start_at: nil, end_at: nil)
+        params = {
+          query: query,
+          direction: direction,
+          start: start_at,
+          end: end_at,
+        }.compact
+
+        _get("/host-attributes/pairs", params) { |json| json }
+      end
+
+      #
+      # Retrieves the host attribute trackers
+      # https://api.passivetotal.org/api/docs/#api-Host_Attributes-GetV2HostAttributesTrackers
+      #
+      # @param [String] query
+      # @param [String, nil] start_at
+      # @param [String, nil] end_at
+      #
+      # @return [Hash]
+      #
+      def trackers(query, start_at: nil, end_at: nil)
+        params = {
+          query: query,
+          start: start_at,
+          end: end_at,
+        }.compact
+
+        _get("/host-attributes/trackers", params) { |json| json }
+      end
+    end
+  end
+end