You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@spot.apache.org by ev...@apache.org on 2017/03/29 16:51:58 UTC
[34/50] [abbrv] incubator-spot git commit: Improving GraphQL
documentation
Improving GraphQL documentation
Project: http://git-wip-us.apache.org/repos/asf/incubator-spot/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-spot/commit/4734f4f6
Tree: http://git-wip-us.apache.org/repos/asf/incubator-spot/tree/4734f4f6
Diff: http://git-wip-us.apache.org/repos/asf/incubator-spot/diff/4734f4f6
Branch: refs/heads/SPOT-35_graphql_api
Commit: 4734f4f6f59e585a4e2d3429243c1e48355cec39
Parents: b165f5e
Author: Diego Ortiz Huerta <di...@intel.com>
Authored: Tue Mar 7 08:16:21 2017 -0800
Committer: Diego Ortiz Huerta <di...@intel.com>
Committed: Wed Mar 15 11:49:48 2017 -0700
----------------------------------------------------------------------
spot-oa/api/graphql/README.md | 13 +++
spot-oa/api/graphql/common.py | 1 +
spot-oa/api/graphql/dns/mutation.py | 28 +++---
spot-oa/api/graphql/dns/query.py | 111 ++++++++++++-----------
spot-oa/api/graphql/flow/mutation.py | 38 ++++----
spot-oa/api/graphql/flow/query.py | 133 ++++++++++++++++++----------
spot-oa/api/graphql/proxy/mutation.py | 56 +++++++-----
spot-oa/api/graphql/proxy/query.py | 107 +++++++++++++---------
spot-oa/api/graphql/schema.py | 9 +-
spot-oa/api/resources/configurator.pyc | Bin 1706 -> 0 bytes
spot-oa/ui/README.md | 1 +
11 files changed, 308 insertions(+), 189 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-spot/blob/4734f4f6/spot-oa/api/graphql/README.md
----------------------------------------------------------------------
diff --git a/spot-oa/api/graphql/README.md b/spot-oa/api/graphql/README.md
new file mode 100644
index 0000000..17fd7f6
--- /dev/null
+++ b/spot-oa/api/graphql/README.md
@@ -0,0 +1,13 @@
+# Apache Spot (incubating) - GraphQL API
+
+Provides an endpoint to send GraphQL queries to access and modify data.
+
+1. Install Spot OA. Follow this [guide](../../README.md#installation).
+2. Start Spot OA Web Server.
+ 1. From spot-oa dir, run ./runIpython.sh
+3. Apache Spot will deploy a GraphQL endpoint under /graphql URL
+
+## Development mode and GraphiQL UI
+
+When Spot OA Web server is started in [development mode](../../ui/README.md#developmentdebugging-process), a GraphiQL UI will be enabled at /graphql URL. Use
+this tool to play with our GraphQL API and to explore the entities we have made available.
http://git-wip-us.apache.org/repos/asf/incubator-spot/blob/4734f4f6/spot-oa/api/graphql/common.py
----------------------------------------------------------------------
diff --git a/spot-oa/api/graphql/common.py b/spot-oa/api/graphql/common.py
index 2c2e9bd..1e34674 100644
--- a/spot-oa/api/graphql/common.py
+++ b/spot-oa/api/graphql/common.py
@@ -112,6 +112,7 @@ def create_spot_node_type(name, extra_fields={}):
IngestSummaryType = GraphQLObjectType(
name='SpotIngestSummaryType',
+ description='Number of ingested records',
fields={
'datetime': GraphQLField(
type=SpotDatetimeType,
http://git-wip-us.apache.org/repos/asf/incubator-spot/blob/4734f4f6/spot-oa/api/graphql/dns/mutation.py
----------------------------------------------------------------------
diff --git a/spot-oa/api/graphql/dns/mutation.py b/spot-oa/api/graphql/dns/mutation.py
index de7395f..da93ba6 100644
--- a/spot-oa/api/graphql/dns/mutation.py
+++ b/spot-oa/api/graphql/dns/mutation.py
@@ -27,11 +27,11 @@ ScoreInputType = GraphQLInputObjectType(
),
'dnsQuery': GraphQLInputObjectField(
type=GraphQLString,
- description='Dns query to score'
+ description='Dns query name to score'
),
'clientIp': GraphQLInputObjectField(
type=SpotIpType,
- description='Client\'s ip to score'
+ description='Client IP to score'
)
}
)
@@ -40,13 +40,16 @@ ThreatDetailsInputType = GraphQLInputObjectType(
name='DnsThreatDetailsInputType',
fields={
'total': GraphQLInputObjectField(
- type=GraphQLInt
+ type=GraphQLInt,
+ description='The number of time an IP sent a dns query'
),
'dnsQuery': GraphQLInputObjectField(
- type=GraphQLString
+ type=GraphQLString,
+ description='DNS query name'
),
'clientIp': GraphQLInputObjectField(
- type=SpotIpType
+ type=SpotIpType,
+ description='Client IP address'
)
}
)
@@ -56,26 +59,27 @@ CreateStoryboardInputType = GraphQLInputObjectType(
fields={
'date': GraphQLInputObjectField(
type=SpotDateType,
- description='A reference date for the add comment process. Defaults to today'
+ description='A reference date for the storyboard being created. Defaults to today'
),
'dnsQuery': GraphQLInputObjectField(
type=GraphQLString,
- description='Reference dns query for the comment'
+ description='Threat dns query name'
),
'clientIp': GraphQLInputObjectField(
type=SpotIpType,
- description='Reference client ip for the comment'
+ description='Threat client IP'
),
'title': GraphQLInputObjectField(
type=GraphQLNonNull(GraphQLString),
- description='A title for the comment'
+ description='Threat title'
),
'text': GraphQLInputObjectField(
type=GraphQLNonNull(GraphQLString),
- description='A description text for the comment'
+ description='Threat title description'
),
'threatDetails': GraphQLInputObjectField(
type=GraphQLNonNull(GraphQLList(GraphQLNonNull(ThreatDetailsInputType))),
+ description='Threat details. See DnsThreatInformation.details'
)
}
)
@@ -118,6 +122,7 @@ MutationType = GraphQLObjectType(
fields={
'score': GraphQLField(
type=GraphQLList(SpotOperationOutputType),
+ description='Sets a score value to connections',
args={
'input': GraphQLArgument(
type=GraphQLNonNull(GraphQLList(GraphQLNonNull(ScoreInputType))),
@@ -128,10 +133,11 @@ MutationType = GraphQLObjectType(
),
'createStoryboard': GraphQLField(
type=SpotOperationOutputType,
+ description='Request Spot to create an entry on storyboard for a particular threat',
args={
'input': GraphQLArgument(
type=GraphQLNonNull(CreateStoryboardInputType),
- description='Generates every data needed to move a threat to the storyboard'
+ description='Threat information'
)
},
resolver=lambda root, args, *_: _create_storyboard(args)
http://git-wip-us.apache.org/repos/asf/incubator-spot/blob/4734f4f6/spot-oa/api/graphql/dns/query.py
----------------------------------------------------------------------
diff --git a/spot-oa/api/graphql/dns/query.py b/spot-oa/api/graphql/dns/query.py
index 7b49421..db55a13 100644
--- a/spot-oa/api/graphql/dns/query.py
+++ b/spot-oa/api/graphql/dns/query.py
@@ -20,7 +20,7 @@ SuspiciousType = GraphQLObjectType(
fields={
'frameTime': GraphQLField(
type=SpotDatetimeType,
- description='Date and time of the frame',
+ description='Frame time',
resolver=lambda root, *_: datetime.utcfromtimestamp(int(root.get('unix_tstamp') or 0))
),
'frameLength': GraphQLField(
@@ -30,32 +30,32 @@ SuspiciousType = GraphQLObjectType(
),
'clientIp': GraphQLField(
type=SpotIpType,
- description='Client\'s ip',
+ description='Client\'s IP address',
resolver=lambda root, *_: root.get('ip_dst')
),
'dnsQuery': GraphQLField(
type=GraphQLString,
- description='Dns query sent by client',
+ description='DNS query name',
resolver=lambda root, *_: root.get('dns_qry_name')
),
'dnsQueryClass': GraphQLField(
type=GraphQLInt,
- description='Class of dns query sent by client',
+ description='DNS query class',
resolver=lambda root, *_: int(root.get('dns_qry_class') or '0x0', 16)
),
'dnsQueryType': GraphQLField(
type=GraphQLInt,
- description='Type of dns query send by client',
+ description='DNS query type',
resolver=lambda root, *_: root.get('dns_qry_type') or 0
),
'dnsQueryRcode': GraphQLField(
type=GraphQLInt,
- description='Return code sent to client',
+ description='DNS query response code',
resolver=lambda root, *_: root.get('dns_qry_rcode') or 0
),
'score': GraphQLField(
type=GraphQLFloat,
- description='Machine learning score value',
+ description='Spot ML score value',
resolver=lambda root, *_: root.get('ml_score') or 0
),
'tld': GraphQLField(
@@ -65,42 +65,42 @@ SuspiciousType = GraphQLObjectType(
),
'dnsQueryRep': GraphQLField(
type=GraphQLString,
- description='Reputation of dns query',
+ description='DNS query name reputation metadata',
resolver=lambda root, *_: root.get('query_rep')
),
'clientIpSev': GraphQLField(
type=GraphQLInt,
- description='User\'s score value for client ip',
+ description='Client IP user risk score',
resolver=lambda root, *_: root.get('ip_sev') or 0
),
'dnsQuerySev': GraphQLField(
type=GraphQLInt,
- description='User\'s score value for dns query',
+ description='@deprecated DNS query name user risk score',
resolver=lambda root, *_: root.get('dns_sev') or 0
),
'dnsQueryClassLabel': GraphQLField(
type=GraphQLString,
- description='Human readable representation of dnsQueryClass value',
+ description='DNS query class name',
resolver=lambda root, *_: root.get('dns_qry_class_name')
),
'dnsQueryTypeLabel': GraphQLField(
type=GraphQLString,
- description='Human readable representation of dnsQueryType value',
+ description='DNS query type name',
resolver=lambda root, *_: root.get('dns_qry_type_name')
),
'dnsQueryRcodeLabel': GraphQLField(
type=GraphQLString,
- description='Human readable representation of dnsQueryRcode value',
+ description='DNS query response code name',
resolver=lambda root, *_: root.get('dns_qry_rcode_name')
),
'networkContext': GraphQLField(
type=GraphQLString,
- description='Network context for client ip',
+ description='@deprecated Network context for client ip',
resolver=lambda root, *_: root.get('network_context')
),
'unixTimestamp': GraphQLField(
type=GraphQLInt,
- description='Unix timestamp for this frame',
+ description='Frame unix timestamp',
resolver=lambda root, *_: root.get('unix_tstamp') or 0
)
}
@@ -111,7 +111,7 @@ EdgeDetailsType = GraphQLObjectType(
fields={
'frameTime': GraphQLField(
type=SpotDatetimeType,
- description='Date and time of the frame',
+ description='Frame time',
resolver=lambda root, *_: datetime.utcfromtimestamp(int(root.get('unix_tstamp') or 0))
),
'frameLength': GraphQLField(
@@ -121,57 +121,57 @@ EdgeDetailsType = GraphQLObjectType(
),
'clientIp': GraphQLField(
type=SpotIpType,
- description='Client\'s ip',
+ description='Client\'s IP address',
resolver=lambda root, *_: root.get('ip_dst')
),
'serverIp': GraphQLField(
type=SpotIpType,
- description='Dns server\'s ip',
+ description='DNS server IP address',
resolver=lambda root, *_: root.get('ip_src')
),
'dnsQuery': GraphQLField(
type=GraphQLString,
- description='Dns query sent by client',
+ description='DNS query name',
resolver=lambda root, *_: root.get('dns_qry_name')
),
'dnsQueryClass': GraphQLField(
type=GraphQLInt,
- description='Class of dns query sent by client',
+ description='DNS query class',
resolver=lambda root, *_: int(root.get('dns_qry_class') or '0x0', 16)
),
'dnsQueryType': GraphQLField(
type=GraphQLInt,
- description='Type of dns query send by client',
+ description='DNS query type',
resolver=lambda root, *_: root.get('dns_qry_type') or 0
),
'dnsQueryRcode': GraphQLField(
type=GraphQLInt,
- description='Return code sent to client',
+ description='DNS query response code',
resolver=lambda root, *_: root.get('dns_qry_rcode') or 0
),
'dnsQueryClassLabel': GraphQLField(
type=GraphQLString,
- description='Human readable representation of dnsQueryClass value',
+ description='DNS query class name',
resolver=lambda root, *_: root.get('dns_qry_class_name')
),
'dnsQueryTypeLabel': GraphQLField(
type=GraphQLString,
- description='Human readable representation of dnsQueryType value',
+ description='DNS query type name',
resolver=lambda root, *_: root.get('dns_qry_type_name')
),
'dnsQueryRcodeLabel': GraphQLField(
type=GraphQLString,
- description='Human readable representation of dnsQueryRcode value',
+ description='DNS query response code name',
resolver=lambda root, *_: root.get('dns_qry_rcode_name')
),
'dnsQueryAnswers': GraphQLField(
type=GraphQLList(GraphQLString),
- description='Dns server\'s answers to query sent by client',
+ description='DNS answers',
resolver=lambda root, *_: root.get('dns_a', '').split('|')
),
'unixTimestamp': GraphQLField(
type=GraphQLInt,
- description='Unix timestamp for this frame',
+ description='Frame unix timestamp',
resolver=lambda root, *_: root.get('unix_tstamp') or 0
)
}
@@ -182,17 +182,17 @@ ThreatDetailsType = GraphQLObjectType(
fields={
'total': GraphQLField(
type=GraphQLInt,
- description='Total threats',
+ description='The number of time an IP sent a dns query',
resolver=lambda root, *_: root.get('total')
),
'dnsQuery': GraphQLField(
type=GraphQLString,
- description='Dns Threats',
+ description='DNS query name',
resolver=lambda root, *_: root.get('dns_qry_name')
),
'clientIp': GraphQLField(
type=SpotIpType,
- description='Ip Threats',
+ description='Client IP address',
resolver=lambda root, *_: root.get('ip_dst')
)
}
@@ -203,12 +203,12 @@ IpDetailsType = GraphQLObjectType(
fields={
'dnsQuery': GraphQLField(
type=GraphQLString,
- description='',
+ description='DNS query name',
resolver=lambda root, *_: root.get('dns_qry_name')
),
'dnsQueryAnswers': GraphQLField(
type=GraphQLList(GraphQLString),
- description='Dns server\'s answers to query sent by client',
+ description='DNS answers',
resolver=lambda root, *_: root.get('dns_a', '').split('|')
)
}
@@ -217,27 +217,29 @@ IpDetailsType = GraphQLObjectType(
ScoredThreatType = GraphQLObjectType(
name='DnsScoredThreatType',
fields={
- 'frameTime': GraphQLField(
+ 'datetime': GraphQLField(
type=SpotDatetimeType,
description='Date and time of user score',
resolver=lambda root, *_: datetime.utcfromtimestamp(int(root.get('unix_tstamp') or 0))
),
'dnsQuery': GraphQLField(
type=GraphQLString,
- description='A dns query that has been scored as high risk (1)',
+ description='DNS query name',
resolver=lambda root, *_: root.get('dns_qry_name')
),
'clientIp': GraphQLField(
type=SpotIpType,
- description='A client ip that has been scored as high risk (1)',
+ description='Client\'s IP address',
resolver=lambda root, *_: root.get('ip_dst')
),
'dnsScore': GraphQLField(
type=GraphQLInt,
+ description='DNS query name risk score value. 1->High, 2->Medium, 3->Low',
resolver=lambda root, *_: root.get('dns_sev') or 0
),
'clientIpScore': GraphQLField(
type=GraphQLInt,
+ description='Client IP address risk score value. 1->High, 2->Medium, 3->Low',
resolver=lambda root, *_: root.get('ip_sev') or 0
)
}
@@ -258,16 +260,17 @@ QueryCommentType = GraphQLObjectType(
fields={
'dnsQuery': GraphQLField(
type=GraphQLString,
+ description='High risk DNS query name',
resolver=lambda root, *_: root.get('dns_threat')
),
'title': GraphQLField(
type=GraphQLString,
- description='A title for the comment',
+ description='Threat title',
resolver=lambda root, *_: root.get('title')
),
'text': GraphQLField(
type=GraphQLString,
- description='A title for the comment',
+ description='Threat description',
resolver=lambda root, *_: root.get('text')
)
}
@@ -279,14 +282,17 @@ ClientIpCommentType = GraphQLObjectType(
fields={
'clientIp': GraphQLField(
type=SpotIpType,
+ description='High risk client IP address',
resolver=lambda root, *_: root.get('ip_threat')
),
'title': GraphQLField(
type=GraphQLString,
+ description='Threat title',
resolver=lambda root, *_: root.get('title')
),
'text': GraphQLField(
type=GraphQLString,
+ description='Threat description',
resolver=lambda root, *_: root.get('text')
)
}
@@ -297,7 +303,7 @@ ThreatsInformationType = GraphQLObjectType(
fields={
'list': GraphQLField(
type=GraphQLList(ScoredThreatType),
- description='List of dns queries or client ips that have been scored as high risk (1)',
+ description='List of DNS query names or client IPs that have been scored',
args={
'date': GraphQLArgument(
type=SpotDateType,
@@ -340,6 +346,7 @@ IncidentProgressionClientIpType = GraphQLObjectType(
),
'clientIp': GraphQLField(
type=SpotIpType,
+ description='Client\'s IP address',
resolver=lambda root, *_: root.get('ip_dst')
)
}
@@ -355,6 +362,7 @@ IncidentProgressionQueryType = GraphQLObjectType(
),
'dnsQuery': GraphQLField(
type=GraphQLString,
+ description='DNS query name',
resolver=lambda root, *_: root.get('dns_qry_name')
)
}
@@ -365,7 +373,7 @@ ThreatInformationType = GraphQLObjectType(
fields={
'incidentProgression': GraphQLField(
type=GraphQLList(IncidentProgressionInterface),
- description='Incident progression information',
+ description='Details the type of connections that conform the activity related to the threat',
args={
'date': GraphQLArgument(
type=SpotDateType,
@@ -392,14 +400,15 @@ ThreatInformationType = GraphQLObjectType(
),
'dnsQuery': GraphQLArgument(
type=GraphQLString,
- description='DNS query of interest'
+ description='DNS query name of interest'
),
'clientIp': GraphQLArgument(
type=SpotIpType,
- description='Ip of interest'
+ description='Client IP address of interest'
),
'first': GraphQLArgument(
- type=GraphQLInt
+ type=GraphQLInt,
+ description='The number of records to return'
)
},
resolver=lambda root, args, *_: Dns.expanded_search(
@@ -416,26 +425,26 @@ QueryType = GraphQLObjectType(
fields={
'suspicious': GraphQLField(
type=GraphQLList(SuspiciousType),
- description='Suspicious dns queries',
+ description='Suspicious DNS query names',
args={
'date': GraphQLArgument(
type=SpotDateType,
- description='A date to use as a reference for suspicous connections. Defaults to today'
+ description='A date to use as a reference for suspicious connections. Defaults to today'
),
'clientIp': GraphQLArgument(
type=SpotIpType,
- description='Ip of interest'
+ description='Client IP of interest'
),
'dnsQuery': GraphQLArgument(
type=GraphQLString,
- description='Partial query of interest'
+ description='Partial query name of interest'
)
},
resolver=lambda root, args, *_: Dns.suspicious_queries(date=args.get('date', date.today()), ip=args.get('clientIp'), query=args.get('dnsQuery'))
),
'edgeDetails': GraphQLField(
type=GraphQLList(EdgeDetailsType),
- description='Dns queries between client and dns server around a particular moment in time',
+ description='DNS queries between client and DNS server around a particular moment in time',
args={
'frameTime': GraphQLArgument(
type=GraphQLNonNull(SpotDatetimeType),
@@ -443,14 +452,14 @@ QueryType = GraphQLObjectType(
),
'dnsQuery': GraphQLArgument(
type=GraphQLNonNull(GraphQLString),
- description='Dns query of interest'
+ description='DNS query name of interest'
)
},
resolver=lambda root, args, *_: Dns.details(frame_time=args.get('frameTime'), query=args.get('dnsQuery'))
),
'ipDetails': GraphQLField(
type=GraphQLList(IpDetailsType),
- description='Queries made by client',
+ description='Query names made by client',
args={
'date': GraphQLArgument(
type=SpotDateType,
@@ -458,7 +467,7 @@ QueryType = GraphQLObjectType(
),
'clientIp': GraphQLArgument(
type=GraphQLNonNull(SpotIpType),
- description='Client\'s ip'
+ description='Client\'s IP address'
)
},
resolver=lambda root, args, *_: Dns.client_details(date=args.get('date', date.today()), ip=args.get('clientIp'))
@@ -475,7 +484,7 @@ QueryType = GraphQLObjectType(
),
'ingestSummary': GraphQLField(
type=GraphQLList(IngestSummaryType),
- description='Total of ingested dns queries',
+ description='Summary of ingested DNS records in range',
args={
'startDate': GraphQLArgument(
type=GraphQLNonNull(SpotDateType),
http://git-wip-us.apache.org/repos/asf/incubator-spot/blob/4734f4f6/spot-oa/api/graphql/flow/mutation.py
----------------------------------------------------------------------
diff --git a/spot-oa/api/graphql/flow/mutation.py b/spot-oa/api/graphql/flow/mutation.py
index d4f5d7f..7650f7e 100644
--- a/spot-oa/api/graphql/flow/mutation.py
+++ b/spot-oa/api/graphql/flow/mutation.py
@@ -28,19 +28,19 @@ ScoreInputType = GraphQLInputObjectType(
),
'srcIp': GraphQLInputObjectField(
type=SpotIpType,
- description='Source ip'
+ description='Source IP to score'
),
'dstIp': GraphQLInputObjectField(
type=SpotIpType,
- description='Destination ip'
+ description='Destination IP to score'
),
'srcPort': GraphQLInputObjectField(
type=GraphQLInt,
- description='Source port'
+ description='Source port to score'
),
'dstPort': GraphQLInputObjectField(
type=GraphQLInt,
- description='Destination port'
+ description='Destination port to score'
)
}
)
@@ -50,19 +50,19 @@ ThreatDetailsInputType = GraphQLInputObjectType(
fields={
'firstSeen': GraphQLInputObjectField(
type=SpotDatetimeType,
- description='First time two ips were seen on one day data of network traffic'
+ description='First time two IPs were seen on a particular day of flow traffic data'
),
'lastSeen': GraphQLInputObjectField(
type=SpotDatetimeType,
- description='Last time two ips were seen on one day data of network trafic'
+ description='Last time two IPs were seen on a particular day of flow traffic data'
),
'srcIp': GraphQLInputObjectField(
type=SpotIpType,
- description='Source ip'
+ description='Source IP address'
),
'dstIp': GraphQLInputObjectField(
type=SpotIpType,
- description='Destination ip'
+ description='Destination IP address'
),
'srcPort': GraphQLInputObjectField(
type=GraphQLInt,
@@ -74,7 +74,7 @@ ThreatDetailsInputType = GraphQLInputObjectType(
),
'connections': GraphQLInputObjectField(
type=GraphQLInt,
- description='Number of connections on one day of network traffic'
+ description='Number of connections on a particular day of flow traffic data'
),
'maxPkts': GraphQLInputObjectField(
type=GraphQLInt,
@@ -82,7 +82,7 @@ ThreatDetailsInputType = GraphQLInputObjectType(
),
'avgPkts': GraphQLInputObjectField(
type=GraphQLInt,
- description='Average number of packets transferred bwteen ips'
+ description='Average number of packets transferred bwteen IPs'
),
'maxBytes': GraphQLInputObjectField(
type=GraphQLInt,
@@ -90,7 +90,7 @@ ThreatDetailsInputType = GraphQLInputObjectType(
),
'avgBytes': GraphQLInputObjectField(
type=GraphQLInt,
- description='Average number of bytes transferred bwteen ips'
+ description='Average number of bytes transferred bwteen IPs'
)
}
)
@@ -100,25 +100,27 @@ CreateStoryboardInputType = GraphQLInputObjectType(
fields={
'date': GraphQLInputObjectField(
type=SpotDateType,
- description='A reference date for the add comment process. Defaults to today'
+ description='A reference date for the storyboard being created. Defaults to today'
),
'ip': GraphQLInputObjectField(
type=GraphQLNonNull(SpotIpType),
- description='Reference IP for the comment'
+ description='High risk IP address'
),
'title': GraphQLInputObjectField(
type=GraphQLNonNull(GraphQLString),
- description='A title for the comment'
+ description='Threat title'
),
'text': GraphQLInputObjectField(
type=GraphQLNonNull(GraphQLString),
- description='A description text for the comment'
+ description='Threat title description'
),
'threatDetails': GraphQLInputObjectField(
type=GraphQLNonNull(GraphQLList(ThreatDetailsInputType)),
+ description='Threat details. See NetflowThreatInformation.details'
),
'first': GraphQLInputObjectField(
- type=GraphQLInt
+ type=GraphQLInt,
+ description='The number of records to return'
)
}
)
@@ -156,6 +158,7 @@ MutationType = GraphQLObjectType(
fields={
'score': GraphQLField(
type=GraphQLList(SpotOperationOutputType),
+ description='Sets a score value to connections',
args={
'input': GraphQLArgument(
type=GraphQLNonNull(GraphQLList(GraphQLNonNull(ScoreInputType))),
@@ -166,10 +169,11 @@ MutationType = GraphQLObjectType(
),
'createStoryboard': GraphQLField(
type=SpotOperationOutputType,
+ description='Request Spot to create an entry on storyboard for a particular threat',
args={
'input': GraphQLArgument(
type=GraphQLNonNull(CreateStoryboardInputType),
- description='Generates every data needed to move a threat to the storyboard'
+ description='Threat information'
)
},
resolver=lambda root, args, *_: _create_storyboard(args)
http://git-wip-us.apache.org/repos/asf/incubator-spot/blob/4734f4f6/spot-oa/api/graphql/flow/query.py
----------------------------------------------------------------------
diff --git a/spot-oa/api/graphql/flow/query.py b/spot-oa/api/graphql/flow/query.py
index 138ee98..3806de9 100644
--- a/spot-oa/api/graphql/flow/query.py
+++ b/spot-oa/api/graphql/flow/query.py
@@ -19,82 +19,102 @@ SuspiciousType = GraphQLObjectType(
fields={
'tstart': GraphQLField(
type=SpotDatetimeType,
+ description='Time the flow was received by the flow collector',
resolver=lambda root, *_: root.get('tstart')
),
'srcIp': GraphQLField(
type=GraphQLString,
+ description='Source IP address',
resolver=lambda root, *_: root.get('srcip')
),
'dstIp': GraphQLField(
type=GraphQLString,
+ description='Destination IP address',
resolver=lambda root, *_: root.get('dstip')
),
'srcPort': GraphQLField(
type=GraphQLInt,
+ description='Source port',
resolver=lambda root, *_: root.get('sport') or 0
),
'dstPort': GraphQLField(
type=GraphQLInt,
+ description='Destination port',
resolver=lambda root, *_: root.get('dport') or 0
),
'protocol': GraphQLField(
type=GraphQLString,
+ description='IP protocol',
resolver=lambda root, *_: root.get('proto')
),
'inPkts': GraphQLField(
type=GraphQLInt,
+ description='Input packets',
resolver=lambda root, *_: root.get('ipkt') or 0
),
'inBytes': GraphQLField(
type=GraphQLInt,
+ description='Input bytes',
resolver=lambda root, *_: root.get('ibyt') or 0
),
'outPkts': GraphQLField(
type=GraphQLInt,
+ description='Output packets',
resolver=lambda root, *_: root.get('opkt') or 0
),
'outBytes': GraphQLField(
type=GraphQLInt,
+ description='Output bytes',
resolver=lambda root, *_: root.get('obyt') or 0
),
'score': GraphQLField(
type=GraphQLFloat,
+ description='Spot ML score',
resolver=lambda root, *_: root.get('ml_score') or 0
),
'rank': GraphQLField(
type=GraphQLInt,
+ description='Spot ML rank',
resolver=lambda root, *_: root.get('rank') or 0
),
'srcIp_isInternal': GraphQLField(
type=GraphQLBoolean,
+ description='Internal source IP address context flag',
resolver=lambda root, *_: root.get('srcip_internal') == '1'
),
'dstIp_isInternal': GraphQLField(
type=GraphQLBoolean,
+ description='Internal destionation IP address context flag',
resolver=lambda root, *_: root.get('dstip_internal') == '1'
),
'srcIp_geoloc': GraphQLField(
type=GraphQLString,
+ description='Source IP geolocation',
resolver=lambda root, *_: root.get('src_geoloc')
),
'dstIp_geoloc': GraphQLField(
type=GraphQLString,
+ description='Destination IP geolocation',
resolver=lambda root, *_: root.get('dst_geoloc')
),
'srcIp_domain': GraphQLField(
type=GraphQLString,
+ description='Source IP domain',
resolver=lambda root, *_: root.get('src_domain')
),
'dstIp_domain': GraphQLField(
type=GraphQLString,
+ description='Destination IP domain',
resolver=lambda root, *_: root.get('dst_domain')
),
'srcIp_rep': GraphQLField(
type=GraphQLString,
+ description='Source IP reputation metadata',
resolver=lambda root, *_: root.get('src_rep')
),
'dstIp_rep': GraphQLField(
type=GraphQLString,
+ description='Destination IP reputation metadata',
resolver=lambda root, *_: root.get('dst_rep')
)
}
@@ -105,62 +125,77 @@ EdgeDetailsType = GraphQLObjectType(
fields={
'tstart': GraphQLField(
type=SpotDatetimeType,
+ description='Time the flow was received by the flow collector',
resolver=lambda root, *_: root.get('tstart')
),
'srcIp': GraphQLField(
type=GraphQLString,
+ description='Source IP address',
resolver=lambda root, *_: root.get('srcip')
),
'dstIp': GraphQLField(
type=GraphQLString,
+ description='Destination IP address',
resolver=lambda root, *_: root.get('dstip')
),
'srcPort': GraphQLField(
type=GraphQLString,
+ description='Source port',
resolver=lambda root, *_: root.get('sport')
),
'dstPort': GraphQLField(
type=GraphQLString,
+ description='Destination port',
resolver=lambda root, *_: root.get('dport')
),
'protocol': GraphQLField(
type=GraphQLString,
+ description='IP protocol',
resolver=lambda root, *_: root.get('proto')
),
'flags': GraphQLField(
type=GraphQLString,
+ description='TCP flags',
resolver=lambda root, *_: root.get('flags')
),
'tos': GraphQLField(
type=GraphQLString,
+ description='DSCP value',
resolver=lambda root, *_: root.get('tos')
),
'inBytes': GraphQLField(
type=GraphQLInt,
+ description='Input bytes',
resolver=lambda root, *_: root.get('ibyt') or 0
),
'inPkts': GraphQLField(
type=GraphQLInt,
+ description='Input packets',
resolver=lambda root, *_: root.get('ipkt') or 0
),
'inIface': GraphQLField(
type=GraphQLString,
+ description='SNMP input interface id index',
resolver=lambda root, *_: root.get('input')
),
'outIface': GraphQLField(
type=GraphQLString,
+ description='SNMP output interface id index',
resolver=lambda root, *_: root.get('output')
),
'routerIp': GraphQLField(
type=GraphQLString,
+ description='Reporting router IP address',
resolver=lambda root, *_: root.get('rip')
),
'outBytes': GraphQLField(
type=GraphQLInt,
+ description='Output bytes',
resolver=lambda root, *_: root.get('obyt') or 0
),
'outPkts': GraphQLField(
type=GraphQLInt,
+ description='Output packets',
resolver=lambda root, *_: root.get('opkt') or 0
)
}
@@ -171,18 +206,22 @@ IpConnectionDetailsType = GraphQLObjectType(
fields={
'srcIp': GraphQLField(
type=GraphQLString,
+ description='Source IP address',
resolver=lambda root, *_: root.get('srcip')
),
'dstIp': GraphQLField(
type=GraphQLString,
+ description='Destination IP address',
resolver=lambda root, *_: root.get('dstip')
),
'inBytes': GraphQLField(
type=GraphQLInt,
+ description='Input bytes',
resolver=lambda root, *_: root.get('ibyt') or 0
),
'inPkts': GraphQLField(
type=GraphQLInt,
+ description='Input packets',
resolver=lambda root, *_: root.get('ipkt') or 0
)
}
@@ -193,11 +232,12 @@ ScoredConnectionType = GraphQLObjectType(
fields={
'tstart': GraphQLField(
type=SpotDatetimeType,
+ description='Time the flow was received by the flow collector',
resolver=lambda root, *_: root.get('tstart')
),
'srcIp': GraphQLField(
type=SpotIpType,
- description='Source Ip',
+ description='Source IP address',
resolver=lambda root, *_: root.get('srcip')
),
'srcPort': GraphQLField(
@@ -207,7 +247,7 @@ ScoredConnectionType = GraphQLObjectType(
),
'dstIp': GraphQLField(
type=SpotIpType,
- description='Destination Ip',
+ description='Destination IP address',
resolver=lambda root, *_: root.get('dstip')
),
'dstPort': GraphQLField(
@@ -217,7 +257,7 @@ ScoredConnectionType = GraphQLObjectType(
),
'score': GraphQLField(
type=GraphQLInt,
- description='Score value. 1->High, 2->Medium, 3->Low',
+ description='Risk score value. 1->High, 2->Medium, 3->Low',
resolver=lambda root, *_: root.get('score') or 0
)
}
@@ -228,22 +268,22 @@ ThreatDetailsType = GraphQLObjectType(
fields={
'firstSeen': GraphQLField(
type=SpotDatetimeType,
- description='First time two ips were seen on one day data of network traffic',
+ description='First time two IPs were seen on a particular day of flow traffic data',
resolver=lambda root, *_: root.get('firstseen')
),
'lastSeen': GraphQLField(
type=SpotDatetimeType,
- description='Last time two ips were seen on one day data of network trafic',
+ description='Last time two IPs were seen on a particular day of flow traffic data',
resolver=lambda root, *_: root.get('lastseen')
),
'srcIp': GraphQLField(
type=SpotIpType,
- description='Source ip',
+ description='Source IP address',
resolver=lambda root, *_: root.get('srcip')
),
'dstIp': GraphQLField(
type=SpotIpType,
- description='Destination ip',
+ description='Destination IP address',
resolver=lambda root, *_: root.get('dstip')
),
'srcPort': GraphQLField(
@@ -258,7 +298,7 @@ ThreatDetailsType = GraphQLObjectType(
),
'connections': GraphQLField(
type=GraphQLInt,
- description='Number of connections on one day of network traffic',
+ description='Number of connections on a particular day of flow traffic data',
resolver=lambda root, *_: root.get('conns')
),
'maxPkts': GraphQLField(
@@ -268,7 +308,7 @@ ThreatDetailsType = GraphQLObjectType(
),
'avgPkts': GraphQLField(
type=GraphQLInt,
- description='Average number of packets transferred bwteen ips',
+ description='Average number of packets transferred bwteen IPs',
resolver=lambda root, *_: root.get('avgpkts')
),
'maxBytes': GraphQLField(
@@ -278,7 +318,7 @@ ThreatDetailsType = GraphQLObjectType(
),
'avgBytes': GraphQLField(
type=GraphQLInt,
- description='Average number of bytes transferred bwteen ips',
+ description='Average number of bytes transferred bwteen IPs',
resolver=lambda root, *_: root.get('avgbyts')
)
}
@@ -289,14 +329,17 @@ CommentType = GraphQLObjectType(
fields={
'ip': GraphQLField(
type=SpotIpType,
+ description='High risk IP address',
resolver=lambda root, *_: root.get('ip_threat')
),
'title': GraphQLField(
type=GraphQLString,
+ description='Threat title',
resolver=lambda root, *_: root.get('title')
),
'text': GraphQLField(
type=GraphQLString,
+ description='Threat description',
resolver=lambda root, *_: root.get('text')
)
}
@@ -307,11 +350,11 @@ ThreatsInformationType = GraphQLObjectType(
fields={
'list': GraphQLField(
type=GraphQLList(ScoredConnectionType),
- description='List of connections that have been scored',
+ description='List of suspicious IPs that have been scored',
args={
'date': GraphQLArgument(
type=SpotDateType,
- description='A date to use as reference to retrieve the list of scored connections. Defaults to today'
+ description='A date to use as reference to retrieve the list of scored IPs. Defaults to today'
)
},
resolver=lambda root, args, *
@@ -338,7 +381,7 @@ IncidentProgressionNodeType = create_spot_node_type(
ImpactAnalysisNodeType = create_spot_node_type('NetflowImpactAnalysisNodeType', {
'size': GraphQLField(
type=GraphQLInt,
- description='Node size',
+ description='Number of inbound, outbound and two-way connections',
resolver=lambda root, *_: root.get('size') or 0
)
})
@@ -348,7 +391,7 @@ MapViewGeometryType = GraphQLObjectType(
fields={
'coordinates': GraphQLField(
type=GraphQLList(GraphQLFloat),
- description='Geo Latitude and longitude',
+ description='Geo latitude and longitude',
resolver=lambda root, *_: root.get('coordinates')
)
}
@@ -359,12 +402,12 @@ MapViewPropertiesType = GraphQLObjectType(
fields={
'ip': GraphQLField(
type=SpotIpType,
- description='Ip',
+ description='IP',
resolver=lambda root, *_: root.get('ip')
),
'location': GraphQLField(
type=GraphQLString,
- description='Name of the ip\'s location',
+ description='Name of the IP\'s location',
resolver=lambda root, *_: root.get('location')
),
'type': GraphQLField(
@@ -396,12 +439,12 @@ MapViewType = GraphQLObjectType(
fields={
'srcIps': GraphQLField(
type=GraphQLList(MapViewIpType),
- description='A list of source ips',
+ description='A list of source IPs',
resolver=lambda root, *_: root.get('sourceips', [])
),
'dstIps': GraphQLField(
type=GraphQLList(MapViewIpType),
- description='A list of destination ips',
+ description='A list of destination IPs',
resolver=lambda root, *_: root.get('destips', [])
)
}
@@ -422,12 +465,12 @@ TimelineType = GraphQLObjectType(
),
'srcIp': GraphQLField(
type=GraphQLNonNull(SpotIpType),
- description='Source ip',
+ description='Source IP address',
resolver=lambda root, *_: root.get('srcip')
),
'dstIp': GraphQLField(
type=GraphQLNonNull(SpotIpType),
- description='Destination ip',
+ description='Destination IP address',
resolver=lambda root, *_: root.get('dstip')
),
'protocol': GraphQLField(
@@ -442,17 +485,17 @@ TimelineType = GraphQLObjectType(
),
'dstPort': GraphQLField(
type=GraphQLNonNull(GraphQLInt),
- description='Destionation port',
+ description='Destination port',
resolver=lambda root, *_: root.get('dport')
),
'pkts': GraphQLField(
type=GraphQLNonNull(GraphQLInt),
- description='Packets tranferred between ips',
+ description='Packets tranferred between IPs',
resolver=lambda root, *_: root.get('ipkt')
),
'bytes': GraphQLField(
type=GraphQLNonNull(GraphQLInt),
- description='Bytes tranferred between ips',
+ description='Bytes tranferred between IPs',
resolver=lambda root, *_: root.get('ibyt')
)
}
@@ -463,15 +506,15 @@ ThreatInformationType = GraphQLObjectType(
fields={
'details': GraphQLField(
type=GraphQLList(ThreatDetailsType),
- description='Detailed information about a high risk threat',
+ description='Detailed information about a high risk IP',
args={
'date': GraphQLArgument(
type=SpotDateType,
- description='A date to use as reference for incident progression information. Defaults to today'
+ description='A date to use as reference for high rist IP information. Defaults to today'
),
'ip': GraphQLArgument(
type=GraphQLNonNull(SpotIpType),
- description='Threat\'s Ip'
+ description='Suspicious IP'
)
},
resolver=lambda root, args, *
@@ -479,7 +522,7 @@ ThreatInformationType = GraphQLObjectType(
),
'incidentProgression': GraphQLField(
type=IncidentProgressionNodeType,
- description='Incident progression information',
+ description='Details for the type of connections that conform the activity related to the threat',
args={
'date': GraphQLArgument(
type=SpotDateType,
@@ -487,7 +530,7 @@ ThreatInformationType = GraphQLObjectType(
),
'ip': GraphQLArgument(
type=GraphQLNonNull(SpotIpType),
- description='Threat\'s Ip'
+ description='Suspicious IP'
)
},
resolver=lambda root, args, *
@@ -495,7 +538,7 @@ ThreatInformationType = GraphQLObjectType(
),
'impactAnalysis': GraphQLField(
type=ImpactAnalysisNodeType,
- description='Impact analysis information',
+ description='Contains the number of inbound, outbound and two-way connections found related to the suspicious IP',
args={
'date': GraphQLArgument(
type=SpotDateType,
@@ -503,7 +546,7 @@ ThreatInformationType = GraphQLObjectType(
),
'ip': GraphQLArgument(
type=GraphQLNonNull(SpotIpType),
- description='Threat\'s Ip'
+ description='Suspicious IP'
)
},
resolver=lambda root, args, *
@@ -511,7 +554,7 @@ ThreatInformationType = GraphQLObjectType(
),
'geoLocalization': GraphQLField(
type=MapViewType,
- description='Gelocalization info about the ips related to this threat',
+ description='Gelocalization info about the IPs related to this threat',
args={
'date': GraphQLArgument(
type=SpotDateType,
@@ -519,7 +562,7 @@ ThreatInformationType = GraphQLObjectType(
),
'ip': GraphQLArgument(
type=GraphQLNonNull(SpotIpType),
- description='Threat\'s Ip'
+ description='Suspicious IP'
)
},
resolver=lambda root, args, *
@@ -527,7 +570,7 @@ ThreatInformationType = GraphQLObjectType(
),
'timeline': GraphQLField(
type=GraphQLList(TimelineType),
- description='Time based information about this threat',
+ description='Lists \'clusters\' of inbound connections to the IP, grouped by time; showing an overall idea of the times during the day with the most activity',
args={
'date': GraphQLArgument(
type=SpotDateType,
@@ -535,7 +578,7 @@ ThreatInformationType = GraphQLObjectType(
),
'ip': GraphQLArgument(
type=GraphQLNonNull(SpotIpType),
- description='Threat\'s Ip'
+ description='Suspicious Ip'
)
},
resolver=lambda root, args, *
@@ -549,7 +592,7 @@ QueryType = GraphQLObjectType(
fields={
'suspicious': GraphQLField(
type=GraphQLList(SuspiciousType),
- description='Netflow Suspicious connections',
+ description='Flow suspicious connections',
args={
'date': GraphQLArgument(
type=SpotDateType,
@@ -557,7 +600,7 @@ QueryType = GraphQLObjectType(
),
'ip': GraphQLArgument(
type=SpotIpType,
- description='Ip of interest'
+ description='IP of interest'
)
},
resolver=lambda root, args, *
@@ -565,7 +608,7 @@ QueryType = GraphQLObjectType(
),
'edgeDetails': GraphQLField(
type=GraphQLList(EdgeDetailsType),
- description='Network acitvity between two ips around a particular moment in time',
+ description='Flow activity between two IPs around a particular moment in time',
args={
'tstart': GraphQLArgument(
type=GraphQLNonNull(SpotDatetimeType),
@@ -573,11 +616,11 @@ QueryType = GraphQLObjectType(
),
'srcIp': GraphQLArgument(
type=GraphQLNonNull(SpotIpType),
- description='Source ip'
+ description='Source IP address'
),
'dstIp': GraphQLArgument(
type=GraphQLNonNull(SpotIpType),
- description='Destination ip'
+ description='Destination IP address'
)
},
resolver=lambda root, args, *_: Flow.details(
@@ -587,15 +630,15 @@ QueryType = GraphQLObjectType(
),
'ipDetails': GraphQLField(
type=GraphQLList(IpConnectionDetailsType),
- description='Ip network activity details',
+ description='Flow activity details in between IP of interest and other suspicious IPs',
args={
'date': GraphQLArgument(
type=SpotDateType,
- description='A date to use as reference for ip network activity details. Defaults to today'
+ description='A date to use as reference for IP network activity details. Defaults to today'
),
'ip': GraphQLArgument(
type=GraphQLNonNull(SpotIpType),
- description='Ip of interest'
+ description='IP address of interest'
)
},
resolver=lambda root, args, *
@@ -603,17 +646,17 @@ QueryType = GraphQLObjectType(
),
'threats': GraphQLField(
type=ThreatsInformationType,
- description='Advanced inforamtion about threats',
+ description='Advanced information about threats',
resolver=lambda *_: {}
),
'threat': GraphQLField(
type=ThreatInformationType,
- description='Advanced inforamtion about a single threat',
+ description='Advanced information about a single threat',
resolver=lambda *_: {}
),
'ingestSummary': GraphQLField(
type=GraphQLList(IngestSummaryType),
- description='Total of ingested netflows',
+ description='Summary of ingested flows in range',
args={
'startDate': GraphQLArgument(
type=GraphQLNonNull(SpotDateType),
http://git-wip-us.apache.org/repos/asf/incubator-spot/blob/4734f4f6/spot-oa/api/graphql/proxy/mutation.py
----------------------------------------------------------------------
diff --git a/spot-oa/api/graphql/proxy/mutation.py b/spot-oa/api/graphql/proxy/mutation.py
index 09e9fe4..1d08186 100644
--- a/spot-oa/api/graphql/proxy/mutation.py
+++ b/spot-oa/api/graphql/proxy/mutation.py
@@ -36,51 +36,64 @@ ThreatDetailsInputType = GraphQLInputObjectType(
name='ProxyThreatDetailsInputType',
fields={
'datetime': GraphQLInputObjectField(
- type=SpotDatetimeType
+ type=SpotDatetimeType,
+ description='Start time of the request'
),
'clientIp': GraphQLInputObjectField(
- type=SpotIpType
+ type=SpotIpType,
+ description='Client\'s IP address'
),
'username': GraphQLInputObjectField(
- type=GraphQLString
+ type=GraphQLString,
+ description='Username used for authetication'
),
'duration': GraphQLInputObjectField(
- type=GraphQLInt
+ type=GraphQLInt,
+ description='Connection duration'
),
'uri': GraphQLInputObjectField(
- type=GraphQLString
+ type=GraphQLString,
+ description='The original URI requested'
),
'webCategory': GraphQLInputObjectField(
- type=GraphQLString
+ type=GraphQLString,
+ description='Web content categories'
),
'responseCode': GraphQLInputObjectField(
- type=GraphQLInt
+ type=GraphQLInt,
+ description='HTTP response code'
),
'requestMethod': GraphQLInputObjectField(
type=GraphQLString,
- description='Http Method'
+ description='HTTP request method'
),
'userAgent': GraphQLInputObjectField(
type=GraphQLString,
description='Client\'s user agent'
),
'responseContentType': GraphQLInputObjectField(
- type=GraphQLString
+ type=GraphQLString,
+ description='HTTP response content type (MIME)'
),
'referer': GraphQLInputObjectField(
- type=GraphQLString
+ type=GraphQLString,
+ description='The address of the webpage that linked to the resource being requested'
),
'uriPort': GraphQLInputObjectField(
- type=GraphQLInt
+ type=GraphQLInt,
+ description='URI port'
),
'serverIp': GraphQLInputObjectField(
- type=SpotIpType
+ type=SpotIpType,
+ description='The address of the webpage that linked to the resource being requested'
),
'serverToClientBytes': GraphQLInputObjectField(
- type=GraphQLInt
+ type=GraphQLInt,
+ description='Number of bytes sent from appliance to client'
),
'clientToServerBytes': GraphQLInputObjectField(
- type=GraphQLInt
+ type=GraphQLInt,
+ description='Number of bytes sent from client to appliance'
)
}
)
@@ -90,25 +103,27 @@ CreateStoryboardInputType = GraphQLInputObjectType(
fields={
'date': GraphQLInputObjectField(
type=SpotDateType,
- description='A reference date for the add comment process. Defaults to today'
+ description='A reference date for the storyboard being created. Defaults to today'
),
'uri': GraphQLInputObjectField(
type=GraphQLNonNull(GraphQLString),
- description='Reference URI for the comment'
+ description='Threat UI'
),
'title': GraphQLInputObjectField(
type=GraphQLNonNull(GraphQLString),
- description='A title for the comment'
+ description='Threat title'
),
'text': GraphQLInputObjectField(
type=GraphQLNonNull(GraphQLString),
- description='A description text for the comment'
+ description='Threat description'
),
'threatDetails': GraphQLInputObjectField(
type=GraphQLNonNull(GraphQLList(GraphQLNonNull(ThreatDetailsInputType))),
+ description='Threat details. See ProxyThreatInformation.details'
),
'first': GraphQLInputObjectField(
- type=GraphQLInt
+ type=GraphQLInt,
+ description='The number of records to return'
)
}
)
@@ -146,6 +161,7 @@ MutationType = GraphQLObjectType(
fields={
'score': GraphQLField(
type=GraphQLList(SpotOperationOutputType),
+ description='Sets a score value to connections',
args={
'input': GraphQLArgument(
type=GraphQLNonNull(GraphQLList(GraphQLNonNull(ScoreInputType))),
@@ -159,7 +175,7 @@ MutationType = GraphQLObjectType(
args={
'input': GraphQLArgument(
type=GraphQLNonNull(CreateStoryboardInputType),
- description='Generates every data needed to move a threat to the storyboard'
+ description='Request Spot to create an entry on storyboard for a particular threat'
)
},
resolver=lambda root, args, *_: _create_storyboard(args)
http://git-wip-us.apache.org/repos/asf/incubator-spot/blob/4734f4f6/spot-oa/api/graphql/proxy/query.py
----------------------------------------------------------------------
diff --git a/spot-oa/api/graphql/proxy/query.py b/spot-oa/api/graphql/proxy/query.py
index d75a1df..697606c 100644
--- a/spot-oa/api/graphql/proxy/query.py
+++ b/spot-oa/api/graphql/proxy/query.py
@@ -22,17 +22,17 @@ SuspiciousType = GraphQLObjectType(
),
'clientIp': GraphQLField(
type=SpotIpType,
- description='Clent\'s ip',
+ description='Client\'s IP address',
resolver=lambda root, *_: root.get('clientip')
),
'host': GraphQLField(
type=GraphQLString,
- description='Target host of the request',
+ description='Host name from the client request URL',
resolver=lambda root, *_: root.get('host')
),
'requestMethod': GraphQLField(
type=GraphQLString,
- description='HTTP method',
+ description='HTTP request method',
resolver=lambda root, *_: root.get('reqmethod')
),
'userAgent': GraphQLField(
@@ -42,12 +42,12 @@ SuspiciousType = GraphQLObjectType(
),
'responseContentType': GraphQLField(
type=GraphQLString,
- description='HTTP response content type',
+ description='HTTP response content type (MIME)',
resolver=lambda root, *_: root.get('resconttype')
),
'duration': GraphQLField(
type=GraphQLInt,
- description='Duration of the request',
+ description='Connection duration',
resolver=lambda root, *_: root.get('duration')
),
'username': GraphQLField(
@@ -57,12 +57,12 @@ SuspiciousType = GraphQLObjectType(
),
'webCategory': GraphQLField(
type=GraphQLString,
- description='Web category',
+ description='Web content categories',
resolver=lambda root, *_: root.get('webcat')
),
'referer': GraphQLField(
type=GraphQLString,
- description='Request\'s referer',
+ description='The address of the webpage that linked to the resource being requested',
resolver=lambda root, *_: root.get('referer')
),
'responseCode': GraphQLField(
@@ -72,22 +72,22 @@ SuspiciousType = GraphQLObjectType(
),
'uriPort': GraphQLField(
type=GraphQLInt,
- description='URI\'s port',
+ description='URI port',
resolver=lambda root, *_: root.get('uriport')
),
'uriPath': GraphQLField(
type=GraphQLString,
- description='URI\'s path',
+ description='URI path',
resolver=lambda root, *_: root.get('uripath')
),
'uriQuery': GraphQLField(
type=GraphQLString,
- description='URI\'s query',
+ description='URI query',
resolver=lambda root, *_: root.get('uriquery')
),
'serverIp': GraphQLField(
type=SpotIpType,
- description='Server\'s ip',
+ description='Server/Proxy IP',
resolver=lambda root, *_: root.get('serverip')
),
'serverToClientBytes': GraphQLField(
@@ -102,26 +102,27 @@ SuspiciousType = GraphQLObjectType(
),
'uri': GraphQLField(
type=GraphQLString,
- description='The original URL requested',
+ description='The original URI requested',
resolver=lambda root, *_: root.get('fulluri')
),
'score': GraphQLField(
type=GraphQLInt,
- description='Score value assigned by machine learning algorithm',
+ description='Spot ML score value',
resolver=lambda root, *_: root.get('ml_score') or 0
),
'uriRep': GraphQLField(
type=GraphQLString,
- description='URI\'s reputation',
+ description='URI reputation metadata',
resolver=lambda root, *_: root.get('uri_rep')
),
'responseCodeLabel': GraphQLField(
type=GraphQLString,
- description='HTTP response code label',
+ description='HTTP response code name',
resolver=lambda root, *_: root.get('respcode_name')
),
'networkContext': GraphQLField(
type=GraphQLString,
+ description='@deprecated',
resolver=lambda root, *_: root.get('network_context')
)
}
@@ -137,17 +138,17 @@ EdgeDetailsType = GraphQLObjectType(
),
'clientIp': GraphQLField(
type=SpotIpType,
- description='Clent\'s ip',
+ description='Client\'s IP address',
resolver=lambda root, *_: root.get('clientip')
),
'host': GraphQLField(
type=GraphQLString,
- description='Target host of the request',
+ description='Host name from the client request URL',
resolver=lambda root, *_: root.get('host')
),
'webCategory': GraphQLField(
type=GraphQLString,
- description='Web category',
+ description='Web content categories',
resolver=lambda root, *_: root.get('webcat')
),
'responseCode': GraphQLField(
@@ -157,12 +158,12 @@ EdgeDetailsType = GraphQLObjectType(
),
'responseCodeLabel': GraphQLField(
type=GraphQLString,
- description='HTTP response code label',
+ description='HTTP response code name',
resolver=lambda root, *_: root.get('respcode_name')
),
'requestMethod': GraphQLField(
type=GraphQLString,
- description='HTTP method',
+ description='HTTP request method',
resolver=lambda root, *_: root.get('reqmethod')
),
'userAgent': GraphQLField(
@@ -172,22 +173,22 @@ EdgeDetailsType = GraphQLObjectType(
),
'responseContentType': GraphQLField(
type=GraphQLString,
- description='HTTP response content type',
+ description='HTTP response content type (MIME)',
resolver=lambda root, *_: root.get('resconttype')
),
'referer': GraphQLField(
type=GraphQLString,
- description='Request\'s referer',
+ description='The address of the webpage that linked to the resource being requested',
resolver=lambda root, *_: root.get('referer')
),
'uriPort': GraphQLField(
type=GraphQLInt,
- description='URI\'s port',
+ description='URI port',
resolver=lambda root, *_: root.get('uriport')
),
'serverIp': GraphQLField(
type=SpotIpType,
- description='Server\'s ip',
+ description='Server/Proxy IP',
resolver=lambda root, *_: root.get('serverip')
),
'serverToClientBytes': GraphQLField(
@@ -202,7 +203,7 @@ EdgeDetailsType = GraphQLObjectType(
),
'uri': GraphQLField(
type=GraphQLString,
- description='The original URL requested',
+ description='The original URI requested',
resolver=lambda root, *_: root.get('fulluri')
)
}
@@ -223,7 +224,7 @@ ScoredRequestType = GraphQLObjectType(
),
'score': GraphQLField(
type=GraphQLInt,
- description='Score value. 1->High, 2->Medium, 3->Low',
+ description='URI risk score value. 1->High, 2->Medium, 3->Low',
resolver=lambda root, *_: root.get('uri_sev') or 0
)
}
@@ -234,14 +235,17 @@ CommentType = GraphQLObjectType(
fields={
'uri': GraphQLField(
type=GraphQLString,
+ description='High risk URI',
resolver=lambda root, *_: root.get('p_threat')
),
'title': GraphQLField(
type=GraphQLString,
+ description='Threat title',
resolver=lambda root, *_: root.get('title')
),
'text': GraphQLField(
type=GraphQLString,
+ description='Threat description',
resolver=lambda root, *_: root.get('text')
)
}
@@ -252,11 +256,11 @@ ThreatsInformationType = GraphQLObjectType(
fields={
'list': GraphQLField(
type=GraphQLList(ScoredRequestType),
- description='List of requests that have been scored',
+ description='List of URIs that have been scored',
args={
'date': GraphQLArgument(
type=SpotDateType,
- description='A date to use as reference to retrieve the list of scored requests. Defaults to today'
+ description='A date to use as reference to retrieve the list of scored URI. Defaults to today'
)
},
resolver=lambda root, args, *_: Proxy.get_scored_requests(date=args.get('date', date.today()))
@@ -280,35 +284,42 @@ ThreatDetailsType = GraphQLObjectType(
fields={
'datetime': GraphQLField(
type=SpotDatetimeType,
+ description='Start time of the request',
resolver=lambda root, *_: '{} {}'.format(root.get('p_date') or '1970-01-01', root.get('p_time') or '00:00:00')
),
'clientIp': GraphQLField(
type=SpotIpType,
+ description='Client\'s IP address',
resolver=lambda root, *_: root.get('clientip')
),
'username': GraphQLField(
type=GraphQLString,
+ description='Username used for authetication',
resolver=lambda root, *_: root.get('username')
),
'duration': GraphQLField(
type=GraphQLInt,
+ description='Connection duration',
resolver=lambda root, *_: root.get('duration')
),
'uri': GraphQLField(
type=GraphQLString,
+ description='The original URI requested',
resolver=lambda root, *_: root.get('fulluri')
),
'webCategory': GraphQLField(
type=GraphQLString,
+ description='Web content categories',
resolver=lambda root, *_: root.get('webcat')
),
'responseCode': GraphQLField(
type=GraphQLInt,
+ description='HTTP response code',
resolver=lambda root, *_: root.get('respcode')
),
'requestMethod': GraphQLField(
type=GraphQLString,
- description='Http Method',
+ description='HTTP request method',
resolver=lambda root, *_: root.get('reqmethod')
),
'userAgent': GraphQLField(
@@ -318,26 +329,32 @@ ThreatDetailsType = GraphQLObjectType(
),
'responseContentType': GraphQLField(
type=GraphQLString,
+ description='HTTP response content type (MIME)',
resolver=lambda root, *_: root.get('resconttype')
),
'referer': GraphQLField(
type=GraphQLString,
+ description='The address of the webpage that linked to the resource being requested',
resolver=lambda root, *_: root.get('referer')
),
'uriPort': GraphQLField(
type=GraphQLInt,
+ description='URI port',
resolver=lambda root, *_: root.get('uriport')
),
'serverIp': GraphQLField(
type=SpotIpType,
+ description='The address of the webpage that linked to the resource being requested',
resolver=lambda root, *_: root.get('serverip')
),
'serverToClientBytes': GraphQLField(
type=GraphQLInt,
+ description='Number of bytes sent from appliance to client',
resolver=lambda root, *_: root.get('scbytes')
),
'clientToServerBytes': GraphQLField(
type=GraphQLInt,
+ description='Number of bytes sent from client to appliance',
resolver=lambda root, *_: root.get('csbytes')
)
}
@@ -348,12 +365,12 @@ IncidentProgressionRequestType = GraphQLObjectType(
fields={
'clientIp': GraphQLField(
type=SpotIpType,
- description='Client\'s ip',
+ description='Client\'s IP',
resolver=lambda root, *_: root.get('clientip')
),
'referer': GraphQLField(
type=GraphQLString,
- description='URI that refers to Threat\'s URI',
+ description='The address of the webpage that linked to the resource being requested',
resolver=lambda root, *_: root.get('referer')
),
'requestMethod': GraphQLField(
@@ -363,7 +380,7 @@ IncidentProgressionRequestType = GraphQLObjectType(
),
'responseContentType': GraphQLField(
type=GraphQLString,
- description='Response Content Type',
+ description='HTTP response content type (MIME)',
resolver=lambda root, *_: root.get('resconttype')
)
}
@@ -374,7 +391,7 @@ IncidentProgressionType = GraphQLObjectType(
fields={
'uri': GraphQLField(
type=GraphQLString,
- description='Threat\'s URI',
+ description='Threat URI',
resolver=lambda root, *_: root.get('fulluri')
),
'refererFor': GraphQLField(
@@ -395,26 +412,32 @@ TimelineType = GraphQLObjectType(
fields={
'startDatetime': GraphQLField(
type=SpotDatetimeType,
+ description='Connection\'s start time',
resolver=lambda root, *_: root.get('tstart') or '1970-01-01 00:00:00'
),
'endDatetime': GraphQLField(
type=SpotDatetimeType,
+ description='Connection\'s end time',
resolver=lambda root, *_: root.get('tend') or '1970-01-01 00:00:00'
),
'duration': GraphQLField(
type=GraphQLInt,
+ description='Connection duration',
resolver=lambda root, *_: root.get('duration')
),
'clientIp': GraphQLField(
type=SpotIpType,
+ description='Client\'s IP address',
resolver=lambda root, *_: root.get('clientip')
),
'responseCode': GraphQLField(
type=GraphQLInt,
+ description='HTTP response code',
resolver=lambda root, *_: root.get('respcode')
),
'responseCodeLabel': GraphQLField(
type=GraphQLString,
+ description='HTTP response code name',
resolver=lambda root, *_: root.get('respcode_name')
)
}
@@ -429,7 +452,7 @@ ThreatInformationType = GraphQLObjectType(
args={
'date': GraphQLArgument(
type=SpotDateType,
- description='A date to use as reference for incident progression information. Defaults to today'
+ description='A date to use as reference for detailed information. Defaults to today'
),
'uri': GraphQLArgument(
type=GraphQLNonNull(GraphQLString),
@@ -440,7 +463,7 @@ ThreatInformationType = GraphQLObjectType(
),
'incidentProgression': GraphQLField(
type=IncidentProgressionType,
- description='Incident progression information',
+ description='Details the type of connections that conform the activity related to the threat',
args={
'date': GraphQLArgument(
type=SpotDateType,
@@ -448,14 +471,14 @@ ThreatInformationType = GraphQLObjectType(
),
'uri': GraphQLArgument(
type=GraphQLNonNull(GraphQLString),
- description='Threat\'s uri'
+ description='Threat URI'
)
},
resolver=lambda root, args, *_: Proxy.incident_progression(date=args.get('date', date.today()), uri=args.get('uri'))
),
'timeline': GraphQLField(
type=GraphQLList(TimelineType),
- description='Time based information about this threat',
+ description='Lists \'clusters\' of inbound connections to the IP, grouped by time; showing an overall idea of the times during the day with the most activity',
args={
'date': GraphQLArgument(
type=SpotDateType,
@@ -463,7 +486,7 @@ ThreatInformationType = GraphQLObjectType(
),
'uri': GraphQLArgument(
type=GraphQLNonNull(GraphQLString),
- description='Threat\'s URI'
+ description='Threat URI'
)
},
resolver=lambda root, args, *_: Proxy.time_line(date=args.get('date', date.today()), uri=args.get('uri'))
@@ -476,7 +499,7 @@ QueryType = GraphQLObjectType(
fields={
'suspicious': GraphQLField(
type=GraphQLList(SuspiciousType),
- description='Proxy Suspicious requests',
+ description='Proxy suspicious requests',
args={
'date': GraphQLArgument(
type=SpotDateType,
@@ -495,7 +518,7 @@ QueryType = GraphQLObjectType(
),
'edgeDetails': GraphQLField(
type=GraphQLList(EdgeDetailsType),
- description='HTTP requests to a particular uri',
+ description='HTTP requests to a particular URI',
args={
'date': GraphQLArgument(
type=SpotDateType,
@@ -507,7 +530,7 @@ QueryType = GraphQLObjectType(
),
'clientIp': GraphQLArgument(
type=GraphQLNonNull(SpotIpType),
- description='Client\'s ip'
+ description='Client\'s IP'
)
},
resolver=lambda root, args, *_: Proxy.details(date=args.get('date', date.today()), uri=args.get('uri'), ip=args.get('clientIp'))
@@ -524,7 +547,7 @@ QueryType = GraphQLObjectType(
),
'ingestSummary': GraphQLField(
type=GraphQLList(IngestSummaryType),
- description='Total of ingested http requests',
+ description='Summary of ingested proxy records in range',
args={
'startDate': GraphQLArgument(
type=GraphQLNonNull(SpotDateType),
http://git-wip-us.apache.org/repos/asf/incubator-spot/blob/4734f4f6/spot-oa/api/graphql/schema.py
----------------------------------------------------------------------
diff --git a/spot-oa/api/graphql/schema.py b/spot-oa/api/graphql/schema.py
index 3975b6c..488f310 100644
--- a/spot-oa/api/graphql/schema.py
+++ b/spot-oa/api/graphql/schema.py
@@ -14,17 +14,17 @@ SpotSchema = GraphQLSchema(
fields={
'flow': GraphQLField(
type=NetflowQueryType,
- description='Flow information',
+ description='Flow is a network protocol that collects IP traffic information and monitors network traffic',
resolver=lambda *_: {}
),
'dns': GraphQLField(
type=DnsQueryType,
- description='Dns information',
+ description='Domain Name System (DNS) Log Records contains the requests in between clients and DNS servers',
resolver=lambda *_: {}
),
'proxy': GraphQLField(
type=ProxyQueryType,
- description='Proxy Information',
+ description='Proxy Logs contains the requests in between clients and Proxy servers',
resolver=lambda *_: {}
)
}
@@ -34,14 +34,17 @@ SpotSchema = GraphQLSchema(
fields={
'flow': GraphQLField(
type=NetflowMutationType,
+ description='Flow related mutation operations',
resolver=lambda *_: {}
),
'dns': GraphQLField(
type=DnsMutationType,
+ description='DNS related mutation operations',
resolver=lambda *_: {}
),
'proxy': GraphQLField(
type=ProxyMutationType,
+ description='Proxy related mutation operations',
resolver=lambda *_: {}
)
}
http://git-wip-us.apache.org/repos/asf/incubator-spot/blob/4734f4f6/spot-oa/api/resources/configurator.pyc
----------------------------------------------------------------------
diff --git a/spot-oa/api/resources/configurator.pyc b/spot-oa/api/resources/configurator.pyc
deleted file mode 100644
index 04505e0..0000000
Binary files a/spot-oa/api/resources/configurator.pyc and /dev/null differ
http://git-wip-us.apache.org/repos/asf/incubator-spot/blob/4734f4f6/spot-oa/ui/README.md
----------------------------------------------------------------------
diff --git a/spot-oa/ui/README.md b/spot-oa/ui/README.md
index 4b35c86..53c008b 100755
--- a/spot-oa/ui/README.md
+++ b/spot-oa/ui/README.md
@@ -110,6 +110,7 @@ For every path found on this document, "SPOT" refers to the path where Spot UI i
1. Install Spot UI. Follow this [guide](INSTALL.md#install-spot-ui).
2. Run Spot UI. Follow this [guide](INSTALL.md#how-to-run-spot-ui).
+ 1. Set SPOT_DEV env var to 1 to enable GraphiQL UI and run ipython in debug mode.
3. Start watching for code changes
1. $ cd SPOT/ui/PIPELINE/
2. Watch one of the following modules