docs: update

Signed-off-by: Kohei Morita <moritakouhei@graffer.jp>

Author: mrtc0

README.md

@@ -1,13 +1,117 @@
 # waffle-go
 
-Waffle is a library that provides in-app WAF (Web Application Firewall) and RASP (Runtime Application Self Protection) capabilities for your Go web applications.
+Waffle is a library for integrating a Web Application Firewall (WAF) into Go applications.
 
-## Features:
+By embedding the WAF directly within the application rather than at the network boundary, you can achieve more accurate and flexible detection and defense against attacks.
 
-- Adapts to your application stack without configuration
-- Protects against common attacks like injection, XSS, and account takeover
-- Context-aware precise detection
+## Features
+
+- Integration with minimal code changes
+- Protection against common web attacks including XSS, SQL injection, and SSRF
+- Protection against business logic vulnerabilities like Account Takeover
+- Support for popular Go web frameworks and libraries
+
+## Use Cases
+
+- Protecting web applications and APIs from common web attacks
+- Alternative to traditional network-based WAFs for application-level protection
+- Enhanced security for applications using database access and file operations
 
 ## Getting Started
 
-You can find a getting started guide on [waffle website](https://sitebatch.github.io/waffle-website/).
+First, set up the Waffle library.
+
+```bash
+go get github.com/sitebatch/waffle-go
+```
+
+```go
+package main
+
+import (
+    "net/http"
+    "github.com/sitebatch/waffle-go"
+)
+
+func main() {
+    // Start Waffle
+    if err := waffle.Start(); err != nil {
+        // handle error
+    }
+}
+```
+
+Finally, depending on which libraries your application uses, install the Waffle contrib package and apply the middleware or wrapper function.  
+The following libraries are supported:
+
+| Library      | Contrib Package                                                |
+| :----------- | :------------------------------------------------------------- |
+| Gin          | [contrib/gin-gonic/gin](contrib/gin-gonic/gin/README.md)       |
+| Echo         | [contrib/labstack/echo](contrib/labstack/echo/README.md)       |
+| net/http     | [contrib/net/http](contrib/net/http/README.md)                 |
+| gqlgen       | [contrib/99designs/gqlgen](contrib/99designs/gqlgen/README.md) |
+| database/sql | [contrib/database/sql](contrib/database/sql/README.md)         |
+| os           | [contrib/os](contrib/os/README.md)                             |
+
+## Configuration
+
+### Custom Rules
+
+You can provide custom WAF rules:
+
+```go
+waffle.Start(waffle.WithRule(customRuleJSON))
+```
+
+### Error Handling
+
+Set a custom handler to handle Waffle's internal errors.
+
+```go
+waffle.SetErrorHandler(customErrorHandler)
+```
+
+### Event Export
+
+To retrieve events detected by Waffle, configure an exporter using `SetExporter()`.
+
+Waffle provides built-in exporters like `StdoutExporter` for logging detection events and `ChanExporter` for writing to a specified channel, but you can also implement and configure your own custom exporter that meets the required interface.
+
+```go
+waffle.SetExporter(customExporter)
+```
+
+### Logging
+
+Set a custom logger to capture Waffle's internal logs.
+
+```go
+waffle.SetLogger(logger)
+```
+
+## Handling blocking event
+
+When Waffle detects an attack and blocks the request, it returns a `waf.SecurityBlockingError` error type. If you catch this error, you should handle it appropriately—for example, by returning a proper error response to the client.
+This error type can be checked using the `waf.IsSecurityBlockingError` function.
+
+When Waffle's HTTP middleware blocks a request, it automatically returns an HTTP 403 Forbidden response, but it is your responsibility to handle the blocked function call.
+For instance, if a function called during processing at an endpoint attempts to execute a potentially vulnerable SQL query (such as SQL Injection), that function call will be blocked and terminated by returning an error of type `waf.SecurityBlockingError`.
+You can determine whether the block was initiated by the WAF using either `errors.As` or `waf.IsSecurityBlockingError`.
+
+```go
+// Example of handling a blocked SQL query
+
+// Will be blocked due to SQL Injection attempt
+userInput := "1 OR 1 = 1"
+_, err := db.QueryContext(ctx, fmt.Sprintf("SELECT * FROM users WHERE id = '%s'", userInput))
+if err != nil {
+    if waf.IsSecurityBlockingError(err) {
+        // Handle blocked request
+        log.Printf("Blocked request: %v", err)
+        return
+    }
+
+    // Handle other errors
+    log.Fatal(err)
+}
+```

contrib/99designs/gqlgen/README.md

@@ -2,40 +2,59 @@
 
 This package provides a Waffle middleware for [gqlgen](https://gqlgen.com/).
 
-If you are using gqlgen, you can apply protection by Waffle using the `WafMiddleware` provided by this package.
+If you are using gqlgen for GraphQL server, you can apply WAF protection using the `WafMiddleware` provided by this package.
+
+## Installation
+
+```bash
+go get github.com/sitebatch/waffle-go/contrib/99designs/gqlgen
+```
 
 ## Usage
 
 ```go
+package main
+
 import (
+	"net/http"
+	"github.com/99designs/gqlgen/graphql/handler"
+
+	"github.com/sitebatch/waffle-go"
 	"github.com/sitebatch/waffle-go/contrib/99designs/gqlgen"
 	waffleHttp "github.com/sitebatch/waffle-go/contrib/net/http"
 )
 
-mux := http.NewServeMux()
+func main() {
+	mux := http.NewServeMux()
 
-gqlHandler := func() http.HandlerFunc {
-	srv := handler.New(graph.NewExecutableSchema(graph.Config{Resolvers: &graph.Resolver{}}))
-	srv.AddTransport(transport.Options{})
-	srv.AddTransport(transport.GET{})
-	srv.AddTransport(transport.POST{})
+	gqlHandler := func() http.HandlerFunc {
+		srv := handler.New(graph.NewExecutableSchema(graph.Config{
+			Resolvers: &graph.Resolver{},
+		}))
 
-	srv.SetQueryCache(lru.New[*ast.QueryDocument](1000))
+		// Apply Waffle WAF middleware for GraphQL
+		srv.Use(gqlgen.WafMiddleware{})
 
-    // Apply WAF middleware for gqlgen
-	srv.Use(gqlgen.WafMiddleware{})
+		return func(w http.ResponseWriter, r *http.Request) {
+			srv.ServeHTTP(w, r)
+		}
+	}
 
-	srv.Use(extension.Introspection{})
-	srv.Use(extension.AutomaticPersistedQuery{
-		Cache: lru.New[string](100),
-	})
+	mux.Handle("/query", gqlHandler())
 
-	return func(w http.ResponseWriter, r *http.Request) {
-		srv.ServeHTTP(w, r)
+	// Apply WAF middleware for the HTTP server
+	handler := waffleHttp.WafMiddleware(mux)
+
+	// Start Waffle
+	if err := waffle.Start(); err != nil {
+		panic(err)
 	}
-}
 
-mux.Handle("/query", gqlHandler())
-// Apply WAF middleware for the HTTP Server
-handler := waffleHttp.WafMiddleware(mux)
+	srv := &http.Server{
+		Addr:    ":8080",
+		Handler: handler,
+	}
+
+	srv.ListenAndServe()
+}
 ```

contrib/database/sql/README.md

@@ -1,36 +1,67 @@
 # database/sql
 
-This package provides a wrapper for [`database/sql`](https://pkg.go.dev/database/sql) protected by Waffle. By replacing it with a drop-in, you can prevent SQL injection if you are using `database/sql`.
+This package provides a wrapper for [`database/sql`](https://pkg.go.dev/database/sql) protected by Waffle. By using this drop-in replacement, you can prevent SQL injection attacks when using `database/sql`.
 
-# Usage
+## Installation
 
-When executing a statement, use the Waffle database driver instead of `database/sql`. At this time, you need to pass the Waffle's operation `context`.
+```bash
+go get github.com/sitebatch/waffle-go/contrib/database/sql
+```
+
+## Usage
+
+Replace your standard `database/sql` imports with the this package.
 
 ```go
+package main
+
 import (
-   	waffleSQL "github.com/sitebatch/waffle-go/contrib/database/sql"
+	"context"
+	"fmt"
+	"log"
+
+	"github.com/sitebatch/waffle-go"
+	waffleSQL "github.com/sitebatch/waffle-go/contrib/database/sql"
+	"github.com/sitebatch/waffle-go/waf"
 
 	_ "github.com/mattn/go-sqlite3" // or any other database driver
 )
 
-db, err := waffleSQL.Open("<driver>", "<dataSourceName>")
-_, err := database.QueryContext(ctx, "<query>")
-```
+func main() {
+	// Start Waffle
+	if err := waffle.Start(); err != nil {
+		log.Fatal(err)
+	}
 
-If you are using a prepared statement, you can assume that SQL injection will not occur, and Waffle does not check for SQL injection.
+	// Open database connection using Waffle wrapper
+	db, err := waffleSQL.Open("sqlite3", "file::memory:?cache=shared")
+	if err != nil {
+		log.Fatal(err)
+	}
 
-```go
-import (
-   	waffleSQL "github.com/sitebatch/waffle-go/contrib/database/sql"
+	// Create a sample table
+	if _, err := db.Exec("CREATE TABLE users(id int, email text, password text);"); err != nil {
+		panic(err)
+	}
+	defer db.Close()
 
-	_ "github.com/mattn/go-sqlite3" // or any other database driver
-)
+	ctx := context.Background()
 
-db, err := waffleSQL.Open("<driver>", "<dataSourceName>")
-// Waffle does not check for SQL injection in prepared statements.
-_, err := database.PrepareContext(ctx, "<query>")
-```
+	// Execute queries - Waffle will prevent SQL injection
+	userID := "1' OR '1'='1"
+	query := fmt.Sprintf("SELECT * FROM users WHERE id = '%s'", userID)
 
-# Example
+	rows, err := db.QueryContext(ctx, query)
+	if err != nil {
+		if waf.IsSecurityBlockingError(err) {
+			// Handle blocked query
+			log.Printf("Blocked SQL injection attempt: %v", err)
+			return
+		}
 
-See [example/sql](../../../example/sql/).
+		log.Fatal(err)
+		return
+	}
+	defer rows.Close()
+}
+```

contrib/gin-gonic/gin/README.md

@@ -2,7 +2,13 @@
 
 This package provides a Waffle middleware for [gin](https://gin-gonic.com/).
 
-If you are using gin, you can apply protection by Waffle using the `WafMiddleware` provided by this package.
+If you are using Gin web framework, you can apply WAF protection using the `WafMiddleware` provided by this package.
+
+## Installation
+
+```bash
+go get github.com/sitebatch/waffle-go/contrib/gin-gonic/gin
+```
 
 ## Usage
 
@@ -15,10 +21,17 @@ import (
 	ginWaf "github.com/sitebatch/waffle-go/contrib/gin-gonic/gin"
 )
 
-r := gin.Default()
-r.Use(ginWaf.WafMiddleware())
+func main() {
+	r := gin.Default()
+
+	// Apply Waffle WAF middleware
+	r.Use(ginWaf.WafMiddleware())
 
-waffle.Start()
+	// Start Waffle
+	if err := waffle.Start(); err != nil {
+		panic(err)
+	}
 
-r.Run(":8000")
+	r.Run(":8000")
+}
 ```