Improve table docs (#33)

Co-authored-by: Madhushree Ray <[email protected]>

.github/workflows/steampipe-anywhere.yml

@@ -0,0 +1,12 @@
+name: Release Steampipe Anywhere Components
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+
+jobs:
+  anywhere_publish_workflow:
+    uses: turbot/steampipe-workflows/.github/workflows/steampipe-anywhere.yml@main
+    secrets: inherit

README.md

@@ -29,6 +29,18 @@ where
   path = '/full/path/to/file'
 ```
 
+## Engines
+
+This plugin is available for the following engines:
+
+| Engine        | Description
+|---------------|------------------------------------------
+| [Steampipe](https://steampipe.io/docs) | The Steampipe CLI exposes APIs and services as a high-performance relational database, giving you the ability to write SQL-based queries to explore dynamic data. Mods extend Steampipe's capabilities with dashboards, reports, and controls built with simple HCL. The Steampipe CLI is a turnkey solution that includes its own Postgres database, plugin management, and mod support.
+| [Postgres FDW](https://steampipe.io/docs/steampipe_postgres/overview) | Steampipe Postgres FDWs are native Postgres Foreign Data Wrappers that translate APIs to foreign tables. Unlike Steampipe CLI, which ships with its own Postgres server instance, the Steampipe Postgres FDWs can be installed in any supported Postgres database version.
+| [SQLite Extension](https://steampipe.io/docs//steampipe_sqlite/overview) | Steampipe SQLite Extensions provide SQLite virtual tables that translate your queries into API calls, transparently fetching information from your API or service as you request it.
+| [Export](https://steampipe.io/docs/steampipe_export/overview) | Steampipe Plugin Exporters provide a flexible mechanism for exporting information from cloud services and APIs. Each exporter is a stand-alone binary that allows you to extract data using Steampipe plugins without a database.
+| [Turbot Pipes](https://turbot.com/pipes/docs) | Turbot Pipes is the only intelligence, automation & security platform built specifically for DevOps. Pipes provide hosted Steampipe database instances, shared dashboards, snapshots, and more.
+
 ## Developing
 
 Prerequisites:
@@ -68,11 +80,17 @@ Further reading:
 - [Writing plugins](https://steampipe.io/docs/develop/writing-plugins)
 - [Writing your first table](https://steampipe.io/docs/develop/writing-your-first-table)
 
-## Contributing
+## Open Source & Contributing
+
+This repository is published under the [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) (source code) and [CC BY-NC-ND](https://creativecommons.org/licenses/by-nc-nd/2.0/) (docs) licenses. Please see our [code of conduct](https://github.com/turbot/.github/blob/main/CODE_OF_CONDUCT.md). We look forward to collaborating with you!
+
+[Steampipe](https://steampipe.io) is a product produced from this open source software, exclusively by [Turbot HQ, Inc](https://turbot.com). It is distributed under our commercial terms. Others are allowed to make their own distribution of the software, but cannot use any of the Turbot trademarks, cloud services, etc. You can learn more in our [Open Source FAQ](https://turbot.com/open-source).
+
+## Get Involved
 
-Please see the [contribution guidelines](https://github.com/turbot/steampipe/blob/main/CONTRIBUTING.md) and our [code of conduct](https://github.com/turbot/steampipe/blob/main/CODE_OF_CONDUCT.md). All contributions are subject to the [Apache 2.0 open source license](https://github.com/turbot/steampipe-plugin-virustotal/blob/main/LICENSE).
+**[Join #steampipe on Slack →](https://turbot.com/community/join)**
 
-`help wanted` issues:
+Want to help but don't know where to start? Pick up one of the `help wanted` issues:
 
 - [Steampipe](https://github.com/turbot/steampipe/labels/help%20wanted)
 - [VirusTotal Plugin](https://github.com/turbot/steampipe-plugin-virustotal/labels/help%20wanted)

docs/index.md

@@ -8,13 +8,14 @@ short_name: "virustotal"
 description: "Steampipe plugin to query file, domain, URL and IP scanning results from VirusTotal."
 og_description: "Query VirusTotal with SQL! Open source CLI. No DB required."
 og_image: "/images/plugins/turbot/virustotal-social-graphic.png"
+engines: ["steampipe", "sqlite", "postgres", "export"]
 ---
 
 # VirusTotal + Steampipe
 
 [VirusTotal](https://virustotal.com) is an Internet security, file and URL analyzer.
 
-[Steampipe](https://steampipe.io) is an open source CLI to instantly query cloud APIs using SQL.
+[Steampipe](https://steampipe.io) is an open-source zero-ETL engine to instantly query cloud APIs using SQL.
 
 Get VirusTotal scan data for a local file:
 
@@ -70,7 +71,4 @@ connection "virustotal" {
 
 - `api_key` - Your VirusTotal API key.
 
-## Get involved
 
-- Open source: https://github.com/turbot/steampipe-plugin-virustotal
-- Community: [Join #steampipe on Slack →](https://turbot.com/community/join)

docs/tables/virustotal_domain.md

@@ -1,18 +1,38 @@
-# Table: virustotal_domain
+---
+title: "Steampipe Table: virustotal_domain - Query VirusTotal Domain Reports using SQL"
+description: "Allows users to query Domain Reports in VirusTotal, specifically providing detailed information about a domain, including the detection of potentially malicious activities."
+---
 
-Get information about a domain including WHOIS, popularity, DNS and more.
+# Table: virustotal_domain - Query VirusTotal Domain Reports using SQL
 
-Note: An `id` (registered domain name) must be provided in all queries to this table.
+VirusTotal is a free online service that analyzes files and URLs for viruses, worms, trojans and other kinds of malicious content. It aggregates many antivirus products and online scan engines to check for viruses that the user's own antivirus solution may have missed, or to verify against any false positives. Domain Reports in VirusTotal provide detailed information about a domain, including the detection of potentially malicious activities.
+
+## Table Usage Guide
+
+The `virustotal_domain` table provides insights into Domain Reports within VirusTotal. As a cybersecurity analyst, explore domain-specific details through this table, including detections, resolutions, and subdomains. Utilize it to uncover information about domains, such as those linked with malicious activities, the resolved IPs, and the detection of potentially harmful subdomains.
+
+**Important Notes**
+- You must specify the `id` (registered domain name) in the `where` clause to query this table.
 
 ## Examples
 
 ### Get domain information
+Explore the detailed information associated with a specific domain to understand its characteristics and potential security risks. This can be particularly useful for cybersecurity analysis and threat detection.
 
-```sql
+```sql+postgres
 select
   *
 from
   virustotal_domain
 where
-  id = 'steampipe.io'
+  id = 'steampipe.io';
 ```
+
+```sql+sqlite
+select
+  *
+from
+  virustotal_domain
+where
+  id = 'steampipe.io';
+```

docs/tables/virustotal_file.md

@@ -1,55 +1,99 @@
-# Table: virustotal_file
+---
+title: "Steampipe Table: virustotal_file - Query VirusTotal File Reports using SQL"
+description: "Allows users to query VirusTotal File Reports, specifically the detailed file scan reports, providing insights into file's safety information."
+---
 
-Get information about a file including scan results, names often used for the file and more.
+# Table: virustotal_file - Query VirusTotal File Reports using SQL
 
-Note: A `path` (local path to a file) or `id` (hash of the file) must be provided in all queries to this table.
+VirusTotal is a free service that analyzes suspicious files and URLs to detect types of malware, including viruses, worms, and trojans. It aggregates numerous antivirus products and online scan engines to check for viruses that the user's own antivirus solution may have missed, or to verify against any false positives. VirusTotal inspects items with over 70 antivirus scanners and URL/domain blacklisting services.
+
+## Table Usage Guide
+
+The `virustotal_file` table provides insights into file reports within VirusTotal. As a security analyst, explore file-specific details through this table, including scan results, positives found, and scan date. Utilize it to uncover information about files, such as those with potential threats, the detection ratio, and the verification of scan results.
+
+**Important Notes**
+- You must specify either the `path` (ocal path to a file) or the `id` (hash of the file) in the `where` clause to query this table.
 
 ## Examples
 
 ### Get VirusTotal information for a local file
-
+Determine the safety of a local file by analyzing it with VirusTotal. This is useful for verifying downloaded files and avoiding potential security threats.
 Uses a local file to generate the hash to query VirusTotal for information
 about the file.
 
 The file will not be uploaded for scanning, but just used to generate the hash
 to search existing results.
 
-```sql
+
+```sql+postgres
+select
+  *
+from
+  virustotal_file
+where
+  path = '/Users/michael/Downloads/terraform_1.0.1_darwin_amd64.zip';
+```
+
+```sql+sqlite
 select
   *
 from
   virustotal_file
 where
-  path = '/Users/michael/Downloads/terraform_1.0.1_darwin_amd64.zip'
+  path = '/Users/michael/Downloads/terraform_1.0.1_darwin_amd64.zip';
 ```
 
 ### Get file information by ID
+This query allows you to pinpoint the specific details of a file using its unique identifier. It is particularly useful when you need to analyze a file's properties or assess its integrity in a security-focused scenario.
 
-```sql
+```sql+postgres
 select
   *
 from
   virustotal_file
 where
-  id = '8739c76e681f900923b900c9df0ef75cf421d39cabb54650c4b9ad19b6a76d85'
+  id = '8739c76e681f900923b900c9df0ef75cf421d39cabb54650c4b9ad19b6a76d85';
+```
+
+```sql+sqlite
+select
+  *
+from
+  virustotal_file
+where
+  id = '8739c76e681f900923b900c9df0ef75cf421d39cabb54650c4b9ad19b6a76d85';
 ```
 
 ### List alternate names for a file
+This query helps you uncover the alternate names associated with a specific file, which can be useful in identifying potential risks or anomalies associated with that file. This can aid in cybersecurity efforts, ensuring that files are properly identified and assessed for potential threats.
 
-```sql
+```sql+postgres
 select
   jsonb_array_elements_text(names) as name
 from
   virustotal_file
 where
   id = '8739c76e681f900923b900c9df0ef75cf421d39cabb54650c4b9ad19b6a76d85'
 order by
-  name
+  name;
+```
+
+```sql+sqlite
+select
+  json_each.value as name
+from
+  virustotal_file,
+  json_each(names)
+where
+  id = '8739c76e681f900923b900c9df0ef75cf421d39cabb54650c4b9ad19b6a76d85'
+order by
+  name;
 ```
 
 ### Find all scanner results by engine
+Explore the variety of scanner results associated with a specific file. This query is useful in identifying and understanding the different categories of analysis results generated by various engines, aiding in comprehensive security assessment.
 
-```sql
+```sql+postgres
 select
   analysis.key as engine,
   analysis.value ->> 'category' as result
@@ -59,5 +103,18 @@ from
 where
   id = '8739c76e681f900923b900c9df0ef75cf421d39cabb54650c4b9ad19b6a76d85'
 order by
-  engine
+  engine;
 ```
+
+```sql+sqlite
+select
+  analysis.key as engine,
+  json_extract(analysis.value, '$.category') as result
+from
+  virustotal.virustotal_file,
+  json_each(last_analysis_results) as analysis
+where
+  id = '8739c76e681f900923b900c9df0ef75cf421d39cabb54650c4b9ad19b6a76d85'
+order by
+  engine;
+```

docs/tables/virustotal_ip.md

@@ -1,25 +1,46 @@
-# Table: virustotal_ip
+---
+title: "Steampipe Table: virustotal_ip - Query VirusTotal IP Addresses using SQL"
+description: "Allows users to query IP Addresses in VirusTotal, providing insights into the detection of URLs, downloadable files, and additional information related to IP addresses."
+---
 
-Get information about an IP including WHOIS, popularity, DNS and more.
+# Table: virustotal_ip - Query VirusTotal IP Addresses using SQL
 
-Note: An `id` (IP address) must be provided in all queries to this table.
+VirusTotal is a service that analyzes files and URLs for viruses, worms, trojans, and other kinds of malicious content. It aggregates many antivirus products and online scan engines to check for viruses that the user's own antivirus may have missed. VirusTotal also provides information regarding IP addresses, including the detection of URLs, downloadable files, and additional data.
+
+## Table Usage Guide
+
+The `virustotal_ip` table provides insights into IP addresses within VirusTotal. As a cybersecurity analyst, explore IP-specific details through this table, including detections of URLs, downloadable files, and additional information. Utilize it to uncover information about IP addresses, such as those associated with malicious activities, and to verify the safety of certain IPs.
+
+**Important Notes**
+- You must specify the `id` (IP address) in the `where` clause to query this table.
 
 ## Examples
 
 ### Get IP information
+Discover the details of a specific IP address to understand its associated risks and behavior. This can be particularly useful in cybersecurity investigations or network monitoring.
 
-```sql
+```sql+postgres
 select
   *
 from
   virustotal_ip
 where
-  id = '76.76.21.21'
+  id = '76.76.21.21';
+```
+
+```sql+sqlite
+select
+  *
+from
+  virustotal_ip
+where
+  id = '76.76.21.21';
 ```
 
 ### Find all scanner results where result was not clean
+Explore scanner results that identified potential threats or issues, providing a valuable tool for cyber security assessments and threat detection.
 
-```sql
+```sql+postgres
 select
   analysis.key as scanner,
   analysis.value ->> 'result' as result
@@ -30,5 +51,19 @@ where
   id = '76.76.21.21'
   and analysis.value ->> 'result' != 'clean'
 order by
-  scanner
+  scanner;
 ```
+
+```sql+sqlite
+select
+  analysis.key as scanner,
+  json_extract(analysis.value, '$.result') as result
+from
+  virustotal.virustotal_ip,
+  json_each(last_analysis_results) as analysis
+where
+  id = '76.76.21.21'
+  and json_extract(analysis.value, '$.result') != 'clean'
+order by
+  scanner;
+```

docs/tables/virustotal_search.md

@@ -1,24 +1,45 @@
-# Table: virustotal_search
+---
+title: "Steampipe Table: virustotal_search - Query VirusTotal Search Results using SQL"
+description: "Allows users to query VirusTotal search results. This table provides a comprehensive view of the antivirus scan results, website scanning, and URL/domain blacklisting."
+---
 
-Perform simple searches for VirusTotal.
+# Table: virustotal_search - Query VirusTotal Search Results using SQL
 
-Note: A search `query` must be provided in all queries to this table.
+VirusTotal is a service that analyzes files and URLs for viruses, worms, trojans, and other kinds of malicious content. It aggregates information from many antivirus and URL scanners to provide a comprehensive view of antivirus scan results, website scanning, and URL/domain blacklisting. This service is useful for detecting malicious content and understanding the security landscape.
+
+## Table Usage Guide
+
+The `virustotal_search` table provides insights into the search results from VirusTotal. As a security analyst, explore the details of antivirus scan results, website scanning, and URL/domain blacklisting through this table. Utilize it to uncover information about potential security threats, such as malware, trojans, and other malicious content.
+
+**Important Notes**
+- You must specify the `query` in the `where` clause to query this table.
 
 ## Examples
 
 ### Simple searches (free tier)
-
+Explore various internet entities like websites, IP addresses, and file hashes for potential security threats by cross-referencing them with the VirusTotal database. This is useful for identifying potential risks associated with these entities, helping to maintain cybersecurity.
 The free tier only supports simple search terms for hashes and IDs.
 
 This example combines simple searches of different types into a single
 consistent result set.
 
-```sql
+
+```sql+postgres
 select * from virustotal_search where query = 'github.com'
 union
 select * from virustotal_search where query = 'https://turbot.com'
 union
 select * from virustotal_search where query = '76.76.21.21'
 union
-select * from virustotal_search where query = '8739c76e681f900923b900c9df0ef75cf421d39cabb54650c4b9ad19b6a76d85'
+select * from virustotal_search where query = '8739c76e681f900923b900c9df0ef75cf421d39cabb54650c4b9ad19b6a76d85';
 ```
+
+```sql+sqlite
+select * from virustotal_search where query = 'github.com'
+union
+select * from virustotal_search where query = 'https://turbot.com'
+union
+select * from virustotal_search where query = '76.76.21.21'
+union
+select * from virustotal_search where query = '8739c76e681f900923b900c9df0ef75cf421d39cabb54650c4b9ad19b6a76d85';
+```