archive/fscan
1
0
Fork 0
mirror of https://github.com/shadow1ng/fscan.git synced 2026-09-24 04:01:52 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

improve embedded scanner runtime

Browse Source
This commit is contained in:
ZacharyZcR
2026-05-18 14:53:00 +08:00
parent 6bfa05cb45
commit 6605c93dd9
10 changed files with 267 additions and 81 deletions
Download Patch File Download Diff File Expand all files Collapse all files
pkg/fscan/README.md
+6 -3
View File
@@ -20,6 +20,9 @@ func main() {
DisablePing: true,
DisableBrute: true,
Plugins: []string{"ssh", "mysql", "redis"},
OnResult: func(result fscan.Result) {
fmt.Printf("%s %s %s\n", result.Type, result.Target, result.Status)
},
})
results, err := scanner.Scan(context.Background(), fscan.Target{
@@ -30,10 +33,10 @@ func main() {
panic(err)
}
for _, result := range results {
fmt.Printf("%s %s %s\n", result.Type, result.Target, result.Status)
}
fmt.Printf("total results: %d\n", len(results))
}
```
The SDK currently reuses fscan's existing scan core and plugin registry. Calls are serialized internally because the current core still keeps process-wide runtime state.
By default, the SDK runs a conservative service-oriented plugin set and blocks plugins with local side effects or active POC behavior. Set `AllowUnsafePlugins` only when the embedding system explicitly wants those capabilities.
pkg/fscan/scanner.go
+128 -43
View File
@@ -12,6 +12,7 @@ import (
"github.com/shadow1ng/fscan/common"
commonconfig "github.com/shadow1ng/fscan/common/config"
"github.com/shadow1ng/fscan/common/i18n"
"github.com/shadow1ng/fscan/common/output"
"github.com/shadow1ng/fscan/core"
"github.com/shadow1ng/fscan/plugins"
@@ -22,6 +23,56 @@ import (
var scanMu sync.Mutex
var defaultSafePlugins = []string{
"activemq",
"cassandra",
"elasticsearch",
"ftp",
"kafka",
"ldap",
"memcached",
"mongodb",
"mssql",
"mysql",
"neo4j",
"netbios",
"oracle",
"postgresql",
"rabbitmq",
"rdp",
"redis",
"rsync",
"smb",
"smtp",
"ssh",
"telnet",
"vnc",
"webtitle",
}
var unsafePlugins = map[string]struct{}{
"cleaner": {},
"crontask": {},
"download": {},
"forwardshell": {},
"keylogger": {},
"ldpreload": {},
"minidump": {},
"reverseshell": {},
"socks5proxy": {},
"sshkey": {},
"systemdservice": {},
"winbits": {},
"winifeo": {},
"winlogon": {},
"winregistry": {},
"winschtask": {},
"winservice": {},
"winstartup": {},
"winwmi": {},
"webpoc": {},
}
// Scanner runs fscan from another Go process.
type Scanner struct {
config Config
@@ -32,6 +83,12 @@ func NewScanner(config Config) *Scanner {
return &Scanner{config: config}
}
// DefaultSafePlugins returns the plugin set used by the SDK when Config.Plugins
// is empty. The returned slice can be modified by callers.
func DefaultSafePlugins() []string {
return append([]string(nil), defaultSafePlugins...)
}
// Scan runs the scanner for the provided targets and returns structured
// findings. If no targets are provided, Config.Targets is used.
func (s *Scanner) Scan(ctx context.Context, targets ...Target) ([]Result, error) {
@@ -48,24 +105,30 @@ func (s *Scanner) Scan(ctx context.Context, targets ...Target) ([]Result, error)
scanMu.Lock()
defer scanMu.Unlock()
previous := captureRuntime()
defer previous.restore()
var (
mu sync.Mutex
results []Result
)
restoreCallback := common.ReplaceResultCallback(func(raw interface{}) {
if result, ok := decodeCallbackResult(raw); ok {
mu.Lock()
results = append(results, result)
mu.Unlock()
}
})
defer restoreCallback()
for _, target := range targets {
if err := ctx.Err(); err != nil {
return snapshotResults(&mu, results), err
}
if err := s.scanOne(ctx, target); err != nil {
sink := func(raw *output.ScanResult) error {
if result, ok := convertOutputResult(raw); ok {
mu.Lock()
results = append(results, result)
mu.Unlock()
if s.config.OnResult != nil {
s.config.OnResult(result)
}
}
return nil
}
if err := s.scanOne(ctx, target, sink); err != nil {
return snapshotResults(&mu, results), err
}
}
@@ -73,7 +136,7 @@ func (s *Scanner) Scan(ctx context.Context, targets ...Target) ([]Result, error)
return snapshotResults(&mu, results), ctx.Err()
}
func (s *Scanner) scanOne(ctx context.Context, target Target) error {
func (s *Scanner) scanOne(ctx context.Context, target Target, sink common.ResultSink) error {
fv := buildFlagVars(s.config, target)
globalFV := common.GetFlagVars()
*globalFV = *fv
@@ -105,6 +168,7 @@ func (s *Scanner) scanOne(ctx context.Context, target Target) error {
common.InitLogger()
session := common.NewScanSession(cfg, state, globalFV)
session.ResultSink = sink
core.RunScan(ctx, info, session)
return nil
}
@@ -121,6 +185,9 @@ func validateConfig(config Config, targets []Target) error {
if !plugins.Exists(name) {
return fmt.Errorf("fscan: plugin %q not found", name)
}
if !config.AllowUnsafePlugins && !isSafePlugin(name) {
return fmt.Errorf("fscan: plugin %q is not enabled for embedded safe mode", name)
}
}
for _, target := range targets {
if strings.TrimSpace(target.Host) == "" && strings.TrimSpace(target.URL) == "" {
@@ -184,7 +251,7 @@ func buildFlagVars(config Config, target Target) *common.FlagVars {
return &common.FlagVars{
Host: strings.TrimSpace(target.Host),
Ports: formatPorts(ports),
ScanMode: formatPlugins(config.Plugins),
ScanMode: formatPlugins(config),
ThreadNum: threadNum,
ModuleThreadNum: moduleThreads,
TimeoutSec: timeout,
@@ -225,12 +292,16 @@ func buildFlagVars(config Config, target Target) *common.FlagVars {
}
}
func formatPlugins(plugins []string) string {
if len(plugins) == 0 {
func formatPlugins(config Config) string {
pluginNames := config.Plugins
if len(pluginNames) == 0 && !config.AllowUnsafePlugins {
pluginNames = defaultSafePlugins
}
if len(pluginNames) == 0 {
return "all"
}
parts := make([]string, 0, len(plugins))
for _, plugin := range plugins {
parts := make([]string, 0, len(pluginNames))
for _, plugin := range pluginNames {
plugin = strings.TrimSpace(plugin)
if plugin != "" {
parts = append(parts, plugin)
@@ -242,6 +313,20 @@ func formatPlugins(plugins []string) string {
return strings.Join(parts, ",")
}
func isSafePlugin(name string) bool {
name = strings.TrimSpace(name)
if name == "" {
return true
}
if plugins.HasType(name, plugins.PluginTypeLocal) {
return false
}
if _, bad := unsafePlugins[name]; bad {
return false
}
return true
}
func formatPorts(ports []int) string {
if len(ports) == 0 {
return commonconfig.MainPorts
@@ -266,43 +351,43 @@ func secondsOrDefault(value time.Duration, fallback int) int64 {
return seconds
}
func decodeCallbackResult(raw interface{}) (Result, bool) {
item, ok := raw.(map[string]interface{})
if !ok {
func convertOutputResult(raw *output.ScanResult) (Result, bool) {
if raw == nil {
return Result{}, false
}
result := Result{
Type: stringValue(item["type"]),
Target: stringValue(item["target"]),
Status: stringValue(item["status"]),
Details: mapValue(item["details"]),
}
if t, ok := item["time"].(time.Time); ok {
result.Time = t
Time: raw.Time,
Type: string(raw.Type),
Target: raw.Target,
Status: raw.Status,
Details: raw.Details,
}
return result, result.Target != "" || result.Status != ""
}
func stringValue(value interface{}) string {
if s, ok := value.(string); ok {
return s
}
return ""
}
func mapValue(value interface{}) map[string]interface{} {
if value == nil {
return nil
}
if m, ok := value.(map[string]interface{}); ok {
return m
}
return nil
}
func snapshotResults(mu *sync.Mutex, results []Result) []Result {
mu.Lock()
defer mu.Unlock()
return append([]Result(nil), results...)
}
type runtimeSnapshot struct {
flagVars common.FlagVars
config *common.Config
state *common.State
}
func captureRuntime() runtimeSnapshot {
return runtimeSnapshot{
flagVars: *common.GetFlagVars(),
config: common.GetGlobalConfig(),
state: common.GetGlobalState(),
}
}
func (s runtimeSnapshot) restore() {
*common.GetFlagVars() = s.flagVars
common.SetGlobalConfig(s.config)
common.SetGlobalState(s.state)
common.ResetLogger()
}
pkg/fscan/scanner_test.go
+93 -2
View File
@@ -2,9 +2,13 @@ package fscan
import (
"context"
"net"
"strings"
"sync/atomic"
"testing"
"time"
"github.com/shadow1ng/fscan/common"
commonconfig "github.com/shadow1ng/fscan/common/config"
)
@@ -17,8 +21,8 @@ func TestBuildFlagVarsDefaults(t *testing.T) {
if fv.Ports != commonconfig.MainPorts {
t.Fatalf("Ports = %q, want MainPorts", fv.Ports)
}
if fv.ScanMode != "all" {
t.Fatalf("ScanMode = %q, want all", fv.ScanMode)
if fv.ScanMode != formatPlugins(Config{Plugins: DefaultSafePlugins()}) {
t.Fatalf("ScanMode = %q, want safe defaults", fv.ScanMode)
}
if !fv.DisableSave || !fv.Silent || !fv.DisableProgress {
t.Fatalf("embedded defaults should disable output side effects")
@@ -43,6 +47,12 @@ func TestValidateConfig(t *testing.T) {
if err := validateConfig(Config{Plugins: []string{"definitely-missing"}}, []Target{{Host: "127.0.0.1"}}); err == nil {
t.Fatal("expected missing plugin error")
}
if err := validateConfig(Config{Plugins: []string{"webpoc"}}, []Target{{URL: "http://127.0.0.1"}}); err == nil {
t.Fatal("expected unsafe plugin error")
}
if err := validateConfig(Config{Plugins: []string{"webpoc"}, AllowUnsafePlugins: true}, []Target{{URL: "http://127.0.0.1"}}); err != nil {
t.Fatalf("unsafe plugin with opt-in failed: %v", err)
}
if err := validateConfig(Config{}, []Target{{Host: "127.0.0.1", Ports: []int{70000}}}); err == nil {
t.Fatal("expected invalid port error")
}
@@ -64,3 +74,84 @@ func TestScanHonorsCanceledContext(t *testing.T) {
t.Fatalf("Scan error = %v, want context.Canceled", err)
}
}
func TestScanCollectsResultsThroughSessionSink(t *testing.T) {
listener, err := net.Listen("tcp", "127.0.0.1:0")
if err != nil {
t.Fatal(err)
}
defer listener.Close()
go func() {
for {
conn, err := listener.Accept()
if err != nil {
return
}
go func(conn net.Conn) {
defer conn.Close()
_ = conn.SetDeadline(time.Now().Add(2 * time.Second))
_, _ = conn.Write([]byte("220 test FTP\r\n"))
buf := make([]byte, 64)
_, _ = conn.Read(buf)
}(conn)
}
}()
var callbackCalls int32
common.SetResultCallback(func(interface{}) {
atomic.AddInt32(&callbackCalls, 1)
})
defer common.ClearResultCallback()
var streamed int32
scanner := NewScanner(Config{
DisablePing: true,
DisableBrute: true,
Timeout: time.Second,
Threads: 16,
Plugins: []string{"ftp"},
OnResult: func(result Result) {
atomic.AddInt32(&streamed, 1)
},
})
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
port := listener.Addr().(*net.TCPAddr).Port
results, err := scanner.Scan(ctx, Target{Host: "127.0.0.1", Ports: []int{port}})
if err != nil {
t.Fatal(err)
}
if len(results) == 0 {
t.Fatal("expected SDK results")
}
if got := atomic.LoadInt32(&streamed); got != int32(len(results)) {
t.Fatalf("streamed length = %d, want %d", got, len(results))
}
if !hasResult(results, "PORT", "open", "") {
t.Fatalf("missing port result: %#v", results)
}
if !hasResult(results, "SERVICE", "FTP", "ftp") {
t.Fatalf("missing ftp plugin result: %#v", results)
}
if got := atomic.LoadInt32(&callbackCalls); got != 0 {
t.Fatalf("global callback calls = %d, want 0", got)
}
}
func hasResult(results []Result, resultType, statusText, plugin string) bool {
for _, result := range results {
if result.Type != resultType || !strings.Contains(result.Status, statusText) {
continue
}
if plugin == "" {
return true
}
if result.Details != nil && result.Details["plugin"] == plugin {
return true
}
}
return false
}
pkg/fscan/types.go
+5
View File
@@ -25,6 +25,11 @@ type Config struct {
Plugins []string
Ports []int
// AllowUnsafePlugins permits plugins with local side effects or long-lived
// behavior. It is false by default for embedded endpoint use.
AllowUnsafePlugins bool
// OnResult is called for every structured result as it is discovered.
OnResult func(Result)
Timeout time.Duration
Threads int